{ "components": { "parameters": { "ApiVersionDate": { "description": "Pins the request to a dated API version. When omitted, the request uses the original (2025-01-01) request/response shapes, so existing unversioned callers are never broken. Generated SDKs always send the latest version they were built against. An unrecognized value is rejected with a 400. The schemas documented here always describe the latest version.", "in": "header", "name": "Api-Version-Date", "required": false, "schema": { "example": "2026-06-09", "format": "date", "type": "string" } } }, "responses": { "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Forbidden" }, "InvalidParameters": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Invalid Parameters" }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Resource not found" }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Unauthorized" } }, "schemas": { "AccessLevel": { "description": "The access level a given user (or company) has to a product or company.", "enum": [ "no_access", "admin", "customer" ], "type": "string" }, "AccessPassOrder": { "description": "The ways a relation of AccessPasses can be ordered", "enum": [ "active_memberships_count", "created_at", "usd_gmv", "usd_gmv_30_days" ], "type": "string" }, "AccessPassTypes": { "description": "The different types an product can be. Only use 'regular'. The rest are for internal use", "enum": [ "regular", "app", "experience_upsell", "api_only" ], "type": "string" }, "AccessToken": { "description": "A short-lived access token used to authenticate API requests on behalf of a user.", "properties": { "expires_at": { "description": "The timestamp after which this access token is no longer valid and must be refreshed.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "token": { "description": "The signed JWT access token string to include in API request Authorization headers.", "type": "string" } }, "required": [ "token", "expires_at" ], "type": "object" }, "Account": { "properties": { "banner_image_url": { "description": "The URL of the account banner image", "nullable": true, "type": "string" }, "business_type": { "description": "The high-level business category for the account", "nullable": true, "type": "string" }, "country": { "description": "The country the account is located in", "nullable": true, "type": "string" }, "created_at": { "description": "When the account was created, as an ISO 8601 timestamp", "type": "string" }, "description": { "description": "A promotional description for the account", "nullable": true, "type": "string" }, "email": { "description": "The email address of the account owner", "nullable": true, "type": "string" }, "home_preferences": { "items": { "description": "Preferences for the public business home page", "type": "string" }, "type": "array" }, "id": { "description": "The ID of the account, which will look like biz_*************", "type": "string" }, "industry_group": { "description": "The industry group the account belongs to", "nullable": true, "type": "string" }, "industry_type": { "description": "The specific industry vertical the account operates in", "nullable": true, "type": "string" }, "invoice_prefix": { "description": "The prefix used for account invoices", "nullable": true, "type": "string" }, "logo_url": { "description": "The URL of the account logo image", "nullable": true, "type": "string" }, "metadata": { "description": "Arbitrary key/value metadata supplied when the account was created", "type": "object" }, "onboarding_type": { "description": "The type of onboarding the account has completed", "nullable": true, "type": "string" }, "opengraph_image_url": { "description": "The URL of the account Open Graph image", "nullable": true, "type": "string" }, "opengraph_image_variant": { "description": "The account Open Graph image variant", "nullable": true, "type": "string" }, "other_business_description": { "description": "The description of the business type when business_type is other", "nullable": true, "type": "string" }, "other_industry_description": { "description": "The description of the industry type when industry_type is other", "nullable": true, "type": "string" }, "parent_account_id": { "description": "The parent account ID for connected accounts", "nullable": true, "type": "string" }, "require_2fa": { "description": "Whether the account requires authorized users to have two-factor authentication enabled", "type": "boolean" }, "route": { "description": "The account's public route identifier", "type": "string" }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this account", "type": "boolean" }, "show_joined_whops": { "description": "Whether the account appears in joined whops on other accounts", "type": "boolean" }, "show_reviews_dtc": { "description": "Whether reviews are displayed on direct-to-consumer product pages", "type": "boolean" }, "show_user_directory": { "description": "Whether the account shows users in the user directory", "type": "boolean" }, "social_links": { "items": { "$ref": "#/components/schemas/AccountSocialLink", "description": "Social links displayed for the account" }, "type": "array" }, "store_page_config": { "description": "Store page display configuration for the account", "type": "object" }, "target_audience": { "description": "The target audience for this account", "nullable": true, "type": "string" }, "title": { "description": "The display name of the account", "type": "string" }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image", "type": "boolean" }, "wallet": { "$ref": "#/components/schemas/AccountWallet", "description": "The account's primary crypto wallet, or null if none has been provisioned", "nullable": true } }, "required": [ "id", "email", "title", "description", "route", "logo_url", "banner_image_url", "business_type", "country", "home_preferences", "industry_group", "industry_type", "invoice_prefix", "onboarding_type", "opengraph_image_url", "opengraph_image_variant", "other_business_description", "other_industry_description", "require_2fa", "target_audience", "send_customer_emails", "show_joined_whops", "show_reviews_dtc", "show_user_directory", "store_page_config", "parent_account_id", "metadata", "created_at", "use_logo_as_opengraph_image_fallback", "wallet", "social_links" ], "type": "object" }, "AccountLink": { "description": "A temporary, time-limited URL that grants a user access to an external account management page.", "properties": { "expires_at": { "description": "The timestamp after which this account link URL is no longer valid.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "url": { "description": "The temporary URL to redirect the user to for account access. Expires at the time specified by expires_at.", "example": "https://whop.com/payouts/biz_xxxxxxxxx/verify", "type": "string" } }, "required": [ "url", "expires_at" ], "type": "object" }, "AccountLinkUseCases": { "description": "The different use cases for generating an account link.", "enum": [ "account_onboarding", "payouts_portal" ], "type": "string" }, "AccountSocialLink": { "properties": { "id": { "description": "The ID of the social link", "type": "string" }, "title": { "description": "The optional display title for the social link", "nullable": true, "type": "string" }, "url": { "description": "The social link URL", "type": "string" }, "website": { "description": "The social platform for this link", "enum": [ "x", "instagram", "facebook", "tiktok", "youtube", "linkedin", "twitch", "website", "custom" ], "type": "string" } }, "required": [ "id", "website", "url", "title" ], "type": "object" }, "AccountWallet": { "properties": { "address": { "description": "The on-chain address of the wallet", "type": "string" }, "id": { "description": "The ID of the wallet, which will look like wallet_*************", "type": "string" }, "network": { "description": "The blockchain network the wallet lives on", "enum": [ "solana", "ethereum", "bitcoin" ], "type": "string" } }, "required": [ "id", "address", "network" ], "type": "object" }, "Ad": { "description": "An ad belonging to an ad group.", "properties": { "ad_campaign": { "description": "The ad campaign this ad belongs to.", "properties": { "id": { "description": "The unique identifier for this ad campaign.", "example": "adcamp_xxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ad_group": { "description": "The parent ad group this ad belongs to.", "properties": { "id": { "description": "The unique identifier for this ad group.", "example": "adgrp_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "click_through_rate": { "description": "Click-through rate as a fraction of impressions (clicks / impressions, 0–1).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks on this ad in the stats window.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in dollars (spend / clicks). 0 when there are no clicks.", "example": 6.9, "type": "number" }, "cost_per_lead": { "description": "Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.", "example": 6.9, "type": "number" }, "cost_per_purchase": { "description": "Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "frequency": { "description": "Average number of times each person saw an ad (impressions / reach), as reported by the platform.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for this ad.", "example": "ad_xxxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "Total impressions (views) on this ad in the stats window.", "example": 42, "type": "integer" }, "issues": { "description": "Open platform issues affecting this ad, deduplicated per object. Empty when there are none.", "items": { "description": "A platform-reported issue on an ad object (rejection, policy flag, etc.).", "properties": { "category": { "description": "Whop's canonical category for this issue. Null until classified.", "oneOf": [ { "$ref": "#/components/schemas/AdPlatformIssueCategories" }, { "type": "null" } ] }, "created_at": { "description": "When the issue was first reported.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "resolution_status": { "$ref": "#/components/schemas/AdPlatformIssueResolutionStatuses", "description": "Current resolution status." }, "resource_id": { "description": "The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object.", "type": [ "string", "null" ] }, "resource_type": { "description": "The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`.", "type": "string" }, "subtype": { "description": "Finer-grained sub-bucket within the category (e.g. the specific Meta policy for a rejection).", "type": [ "string", "null" ] } }, "required": [ "category", "subtype", "resource_type", "resource_id", "created_at", "resolution_status" ], "type": "object" }, "type": "array" }, "leads": { "description": "Number of Whop pixel-attributed leads (last-click) in the stats window.", "example": 42, "type": "integer" }, "platform": { "$ref": "#/components/schemas/AdCampaignPlatforms", "description": "The external ad platform this ad is running on (e.g., meta, tiktok)." }, "purchase_value": { "description": "Total USD value of Whop pixel-attributed purchases in the stats window.", "example": 6.9, "type": "number" }, "purchases": { "description": "Number of Whop pixel-attributed purchases (last-click) in the stats window.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in the stats window (deduplicated by the platform).", "example": 42, "type": "integer" }, "return_on_ad_spend": { "description": "Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.", "example": 6.9, "type": "number" }, "spend": { "description": "Amount charged in dollars in the stats window.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of `spend` and the other monetary metric fields.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ExternalAdStatuses", "description": "Current delivery status of the ad." }, "title": { "description": "The display title of the ad. Falls back to the creative set caption when unset.", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).", "example": 6.9, "type": [ "number", "null" ] }, "unique_clicks": { "description": "Unique clicks (deduplicated by the platform) in the stats window.", "example": 42, "type": "integer" }, "updated_at": { "description": "When the ad was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "title", "status", "platform", "created_at", "updated_at", "issues", "spend", "spend_currency", "impressions", "reach", "clicks", "unique_clicks", "frequency", "click_through_rate", "unique_click_through_rate", "return_on_ad_spend", "purchases", "purchase_value", "leads", "cost_per_click", "cost_per_mille", "cost_per_result", "cost_per_purchase", "cost_per_lead", "ad_group", "ad_campaign" ], "type": "object" }, "AdBudgetTypes": { "description": "The budget type for an ad campaign or ad group.", "enum": [ "daily", "lifetime" ], "type": "string" }, "AdCampaign": { "description": "An advertising campaign running on an external platform or within Whop.", "properties": { "budget": { "description": "Total budget in dollars.", "example": 6.9, "type": [ "number", "null" ] }, "budget_type": { "oneOf": [ { "$ref": "#/components/schemas/AdBudgetTypes" }, { "type": "null" } ] }, "click_through_rate": { "description": "Click-through rate as a fraction of impressions (clicks / impressions, 0–1).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks on the campaign's ads in the stats window.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in dollars (spend / clicks). 0 when there are no clicks.", "example": 6.9, "type": "number" }, "cost_per_lead": { "description": "Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.", "example": 6.9, "type": "number" }, "cost_per_purchase": { "description": "Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad campaign was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "frequency": { "description": "Average number of times each person saw an ad (impressions / reach), as reported by the platform.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for this ad campaign.", "example": "adcamp_xxxxxxxxxxx", "type": "string" }, "impressions": { "description": "Total impressions (views) on the campaign's ads in the stats window.", "example": 42, "type": "integer" }, "issues": { "description": "Open platform issues affecting this campaign and its descendant ad groups and ads, deduplicated per object. Empty when there are none.", "items": { "description": "A platform-reported issue on an ad object (rejection, policy flag, etc.).", "properties": { "category": { "description": "Whop's canonical category for this issue. Null until classified.", "oneOf": [ { "$ref": "#/components/schemas/AdPlatformIssueCategories" }, { "type": "null" } ] }, "created_at": { "description": "When the issue was first reported.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "resolution_status": { "$ref": "#/components/schemas/AdPlatformIssueResolutionStatuses", "description": "Current resolution status." }, "resource_id": { "description": "The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object.", "type": [ "string", "null" ] }, "resource_type": { "description": "The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`.", "type": "string" }, "subtype": { "description": "Finer-grained sub-bucket within the category (e.g. the specific Meta policy for a rejection).", "type": [ "string", "null" ] } }, "required": [ "category", "subtype", "resource_type", "resource_id", "created_at", "resolution_status" ], "type": "object" }, "type": "array" }, "leads": { "description": "Number of Whop pixel-attributed leads (last-click) in the stats window.", "example": 42, "type": "integer" }, "platform": { "$ref": "#/components/schemas/AdCampaignPlatforms", "description": "The external ad platform this campaign is running on (e.g., meta, tiktok)." }, "purchase_value": { "description": "Total USD value of Whop pixel-attributed purchases in the stats window.", "example": 6.9, "type": "number" }, "purchases": { "description": "Number of Whop pixel-attributed purchases (last-click) in the stats window.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in the stats window (deduplicated by the platform).", "example": 42, "type": "integer" }, "return_on_ad_spend": { "description": "Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.", "example": 6.9, "type": "number" }, "spend": { "description": "Amount charged in dollars in the stats window.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of `spend` and the other monetary metric fields.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/AdCampaignStatuses", "description": "Current status of the campaign." }, "title": { "description": "The campaign name shown in the Whop dashboard.", "type": "string" }, "unique_click_through_rate": { "description": "Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).", "example": 6.9, "type": [ "number", "null" ] }, "unique_clicks": { "description": "Unique clicks (deduplicated by the platform) in the stats window.", "example": 42, "type": "integer" }, "updated_at": { "description": "When the ad campaign was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "title", "status", "platform", "created_at", "updated_at", "budget", "budget_type", "issues", "spend", "spend_currency", "impressions", "reach", "clicks", "unique_clicks", "frequency", "click_through_rate", "unique_click_through_rate", "return_on_ad_spend", "purchases", "purchase_value", "leads", "cost_per_click", "cost_per_mille", "cost_per_result", "cost_per_purchase", "cost_per_lead" ], "type": "object" }, "AdCampaignListItem": { "description": "An advertising campaign running on an external platform or within Whop.", "properties": { "budget": { "description": "Total budget in dollars.", "example": 6.9, "type": [ "number", "null" ] }, "budget_type": { "oneOf": [ { "$ref": "#/components/schemas/AdBudgetTypes" }, { "type": "null" } ] }, "click_through_rate": { "description": "Click-through rate as a fraction of impressions (clicks / impressions, 0–1).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks on the campaign's ads in the stats window.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in dollars (spend / clicks). 0 when there are no clicks.", "example": 6.9, "type": "number" }, "cost_per_lead": { "description": "Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.", "example": 6.9, "type": "number" }, "cost_per_purchase": { "description": "Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad campaign was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "frequency": { "description": "Average number of times each person saw an ad (impressions / reach), as reported by the platform.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for this ad campaign.", "example": "adcamp_xxxxxxxxxxx", "type": "string" }, "impressions": { "description": "Total impressions (views) on the campaign's ads in the stats window.", "example": 42, "type": "integer" }, "issues": { "description": "Open platform issues affecting this campaign and its descendant ad groups and ads, deduplicated per object. Empty when there are none.", "items": { "description": "A platform-reported issue on an ad object (rejection, policy flag, etc.).", "properties": { "category": { "description": "Whop's canonical category for this issue. Null until classified.", "oneOf": [ { "$ref": "#/components/schemas/AdPlatformIssueCategories" }, { "type": "null" } ] }, "created_at": { "description": "When the issue was first reported.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "resolution_status": { "$ref": "#/components/schemas/AdPlatformIssueResolutionStatuses", "description": "Current resolution status." }, "resource_id": { "description": "The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object.", "type": [ "string", "null" ] }, "resource_type": { "description": "The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`.", "type": "string" }, "subtype": { "description": "Finer-grained sub-bucket within the category (e.g. the specific Meta policy for a rejection).", "type": [ "string", "null" ] } }, "required": [ "category", "subtype", "resource_type", "resource_id", "created_at", "resolution_status" ], "type": "object" }, "type": "array" }, "leads": { "description": "Number of Whop pixel-attributed leads (last-click) in the stats window.", "example": 42, "type": "integer" }, "platform": { "$ref": "#/components/schemas/AdCampaignPlatforms", "description": "The external ad platform this campaign is running on (e.g., meta, tiktok)." }, "purchase_value": { "description": "Total USD value of Whop pixel-attributed purchases in the stats window.", "example": 6.9, "type": "number" }, "purchases": { "description": "Number of Whop pixel-attributed purchases (last-click) in the stats window.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in the stats window (deduplicated by the platform).", "example": 42, "type": "integer" }, "return_on_ad_spend": { "description": "Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.", "example": 6.9, "type": "number" }, "spend": { "description": "Amount charged in dollars in the stats window.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of `spend` and the other monetary metric fields.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/AdCampaignStatuses", "description": "Current status of the campaign." }, "title": { "description": "The campaign name shown in the Whop dashboard.", "type": "string" }, "unique_click_through_rate": { "description": "Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).", "example": 6.9, "type": [ "number", "null" ] }, "unique_clicks": { "description": "Unique clicks (deduplicated by the platform) in the stats window.", "example": 42, "type": "integer" }, "updated_at": { "description": "When the ad campaign was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "title", "status", "platform", "created_at", "updated_at", "budget", "budget_type", "issues", "spend", "spend_currency", "impressions", "reach", "clicks", "unique_clicks", "frequency", "click_through_rate", "unique_click_through_rate", "return_on_ad_spend", "purchases", "purchase_value", "leads", "cost_per_click", "cost_per_mille", "cost_per_result", "cost_per_purchase", "cost_per_lead" ], "type": "object" }, "AdCampaignPlatforms": { "description": "The platforms where an ad campaign can run.", "enum": [ "meta", "tiktok" ], "type": "string" }, "AdCampaignStatuses": { "description": "The status of an ad campaign.", "enum": [ "active", "paused", "payment_failed", "draft", "in_review", "flagged" ], "type": "string" }, "AdGroup": { "description": "An ad group belonging to an ad campaign.", "properties": { "ad_campaign": { "description": "The ad campaign this ad group belongs to.", "properties": { "id": { "description": "The unique identifier for this ad campaign.", "example": "adcamp_xxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "budget": { "description": "Budget amount in dollars.", "example": 6.9, "type": [ "number", "null" ] }, "budget_type": { "description": "How the budget is allocated (daily or lifetime).", "oneOf": [ { "$ref": "#/components/schemas/AdBudgetTypes" }, { "type": "null" } ] }, "click_through_rate": { "description": "Click-through rate as a fraction of impressions (clicks / impressions, 0–1).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks on this ad group's ads in the stats window.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in dollars (spend / clicks). 0 when there are no clicks.", "example": 6.9, "type": "number" }, "cost_per_lead": { "description": "Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.", "example": 6.9, "type": "number" }, "cost_per_purchase": { "description": "Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad group was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "frequency": { "description": "Average number of times each person saw an ad (impressions / reach), as reported by the platform.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for this ad group.", "example": "adgrp_xxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "Total impressions (views) on this ad group's ads in the stats window.", "example": 42, "type": "integer" }, "issues": { "description": "Open platform issues affecting this ad group and its descendant ads, deduplicated per object. Empty when there are none.", "items": { "description": "A platform-reported issue on an ad object (rejection, policy flag, etc.).", "properties": { "category": { "description": "Whop's canonical category for this issue. Null until classified.", "oneOf": [ { "$ref": "#/components/schemas/AdPlatformIssueCategories" }, { "type": "null" } ] }, "created_at": { "description": "When the issue was first reported.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "resolution_status": { "$ref": "#/components/schemas/AdPlatformIssueResolutionStatuses", "description": "Current resolution status." }, "resource_id": { "description": "The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object.", "type": [ "string", "null" ] }, "resource_type": { "description": "The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`.", "type": "string" }, "subtype": { "description": "Finer-grained sub-bucket within the category (e.g. the specific Meta policy for a rejection).", "type": [ "string", "null" ] } }, "required": [ "category", "subtype", "resource_type", "resource_id", "created_at", "resolution_status" ], "type": "object" }, "type": "array" }, "leads": { "description": "Number of Whop pixel-attributed leads (last-click) in the stats window.", "example": 42, "type": "integer" }, "platform": { "$ref": "#/components/schemas/AdCampaignPlatforms", "description": "The external ad platform this ad group is running on (e.g., meta, tiktok)." }, "purchase_value": { "description": "Total USD value of Whop pixel-attributed purchases in the stats window.", "example": 6.9, "type": "number" }, "purchases": { "description": "Number of Whop pixel-attributed purchases (last-click) in the stats window.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in the stats window (deduplicated by the platform).", "example": 42, "type": "integer" }, "return_on_ad_spend": { "description": "Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.", "example": 6.9, "type": "number" }, "spend": { "description": "Amount charged in dollars in the stats window.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of `spend` and the other monetary metric fields.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/AdGroupStatuses", "description": "Current operational status of the ad group." }, "title": { "description": "The ad group name shown in the Whop dashboard.", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).", "example": 6.9, "type": [ "number", "null" ] }, "unique_clicks": { "description": "Unique clicks (deduplicated by the platform) in the stats window.", "example": 42, "type": "integer" }, "updated_at": { "description": "When the ad group was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "title", "status", "platform", "created_at", "updated_at", "budget", "budget_type", "issues", "spend", "spend_currency", "impressions", "reach", "clicks", "unique_clicks", "frequency", "click_through_rate", "unique_click_through_rate", "return_on_ad_spend", "purchases", "purchase_value", "leads", "cost_per_click", "cost_per_mille", "cost_per_result", "cost_per_purchase", "cost_per_lead", "ad_campaign" ], "type": "object" }, "AdGroupConfigBidStrategy": { "enum": [ "lowest_cost", "bid_cap", "cost_cap" ], "type": "string" }, "AdGroupConfigBillingEvent": { "enum": [ "impressions", "clicks", "optimized_cpm", "video_views" ], "type": "string" }, "AdGroupConfigOptimizationGoal": { "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "app_installs", "video_views", "lead_generation", "value", "page_likes", "conversations", "ad_recall_lift", "two_second_continuous_video_views", "post_engagement", "event_responses", "reminders_set", "quality_lead" ], "type": "string" }, "AdGroupConfigPacing": { "enum": [ "standard", "accelerated" ], "type": "string" }, "AdGroupListItem": { "description": "An ad group belonging to an ad campaign.", "properties": { "ad_campaign": { "description": "The ad campaign this ad group belongs to.", "properties": { "id": { "description": "The unique identifier for this ad campaign.", "example": "adcamp_xxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "budget": { "description": "Budget amount in dollars.", "example": 6.9, "type": [ "number", "null" ] }, "budget_type": { "description": "How the budget is allocated (daily or lifetime).", "oneOf": [ { "$ref": "#/components/schemas/AdBudgetTypes" }, { "type": "null" } ] }, "click_through_rate": { "description": "Click-through rate as a fraction of impressions (clicks / impressions, 0–1).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks on this ad group's ads in the stats window.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in dollars (spend / clicks). 0 when there are no clicks.", "example": 6.9, "type": "number" }, "cost_per_lead": { "description": "Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.", "example": 6.9, "type": "number" }, "cost_per_purchase": { "description": "Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad group was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "frequency": { "description": "Average number of times each person saw an ad (impressions / reach), as reported by the platform.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for this ad group.", "example": "adgrp_xxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "Total impressions (views) on this ad group's ads in the stats window.", "example": 42, "type": "integer" }, "issues": { "description": "Open platform issues affecting this ad group and its descendant ads, deduplicated per object. Empty when there are none.", "items": { "description": "A platform-reported issue on an ad object (rejection, policy flag, etc.).", "properties": { "category": { "description": "Whop's canonical category for this issue. Null until classified.", "oneOf": [ { "$ref": "#/components/schemas/AdPlatformIssueCategories" }, { "type": "null" } ] }, "created_at": { "description": "When the issue was first reported.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "resolution_status": { "$ref": "#/components/schemas/AdPlatformIssueResolutionStatuses", "description": "Current resolution status." }, "resource_id": { "description": "The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object.", "type": [ "string", "null" ] }, "resource_type": { "description": "The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`.", "type": "string" }, "subtype": { "description": "Finer-grained sub-bucket within the category (e.g. the specific Meta policy for a rejection).", "type": [ "string", "null" ] } }, "required": [ "category", "subtype", "resource_type", "resource_id", "created_at", "resolution_status" ], "type": "object" }, "type": "array" }, "leads": { "description": "Number of Whop pixel-attributed leads (last-click) in the stats window.", "example": 42, "type": "integer" }, "platform": { "$ref": "#/components/schemas/AdCampaignPlatforms", "description": "The external ad platform this ad group is running on (e.g., meta, tiktok)." }, "purchase_value": { "description": "Total USD value of Whop pixel-attributed purchases in the stats window.", "example": 6.9, "type": "number" }, "purchases": { "description": "Number of Whop pixel-attributed purchases (last-click) in the stats window.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in the stats window (deduplicated by the platform).", "example": 42, "type": "integer" }, "return_on_ad_spend": { "description": "Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.", "example": 6.9, "type": "number" }, "spend": { "description": "Amount charged in dollars in the stats window.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of `spend` and the other monetary metric fields.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/AdGroupStatuses", "description": "Current operational status of the ad group." }, "title": { "description": "The ad group name shown in the Whop dashboard.", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).", "example": 6.9, "type": [ "number", "null" ] }, "unique_clicks": { "description": "Unique clicks (deduplicated by the platform) in the stats window.", "example": 42, "type": "integer" }, "updated_at": { "description": "When the ad group was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "title", "status", "platform", "created_at", "updated_at", "budget", "budget_type", "issues", "spend", "spend_currency", "impressions", "reach", "clicks", "unique_clicks", "frequency", "click_through_rate", "unique_click_through_rate", "return_on_ad_spend", "purchases", "purchase_value", "leads", "cost_per_click", "cost_per_mille", "cost_per_result", "cost_per_purchase", "cost_per_lead", "ad_campaign" ], "type": "object" }, "AdGroupStatuses": { "description": "The status of an external ad group.", "enum": [ "active", "paused", "inactive", "in_review", "rejected", "flagged" ], "type": "string" }, "AdListItem": { "description": "An ad belonging to an ad group.", "properties": { "ad_campaign": { "description": "The ad campaign this ad belongs to.", "properties": { "id": { "description": "The unique identifier for this ad campaign.", "example": "adcamp_xxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ad_group": { "description": "The parent ad group this ad belongs to.", "properties": { "id": { "description": "The unique identifier for this ad group.", "example": "adgrp_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "click_through_rate": { "description": "Click-through rate as a fraction of impressions (clicks / impressions, 0–1).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks on this ad in the stats window.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in dollars (spend / clicks). 0 when there are no clicks.", "example": 6.9, "type": "number" }, "cost_per_lead": { "description": "Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.", "example": 6.9, "type": "number" }, "cost_per_purchase": { "description": "Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "frequency": { "description": "Average number of times each person saw an ad (impressions / reach), as reported by the platform.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for this ad.", "example": "ad_xxxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "Total impressions (views) on this ad in the stats window.", "example": 42, "type": "integer" }, "issues": { "description": "Open platform issues affecting this ad, deduplicated per object. Empty when there are none.", "items": { "description": "A platform-reported issue on an ad object (rejection, policy flag, etc.).", "properties": { "category": { "description": "Whop's canonical category for this issue. Null until classified.", "oneOf": [ { "$ref": "#/components/schemas/AdPlatformIssueCategories" }, { "type": "null" } ] }, "created_at": { "description": "When the issue was first reported.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "resolution_status": { "$ref": "#/components/schemas/AdPlatformIssueResolutionStatuses", "description": "Current resolution status." }, "resource_id": { "description": "The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object.", "type": [ "string", "null" ] }, "resource_type": { "description": "The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`.", "type": "string" }, "subtype": { "description": "Finer-grained sub-bucket within the category (e.g. the specific Meta policy for a rejection).", "type": [ "string", "null" ] } }, "required": [ "category", "subtype", "resource_type", "resource_id", "created_at", "resolution_status" ], "type": "object" }, "type": "array" }, "leads": { "description": "Number of Whop pixel-attributed leads (last-click) in the stats window.", "example": 42, "type": "integer" }, "platform": { "$ref": "#/components/schemas/AdCampaignPlatforms", "description": "The external ad platform this ad is running on (e.g., meta, tiktok)." }, "purchase_value": { "description": "Total USD value of Whop pixel-attributed purchases in the stats window.", "example": 6.9, "type": "number" }, "purchases": { "description": "Number of Whop pixel-attributed purchases (last-click) in the stats window.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in the stats window (deduplicated by the platform).", "example": 42, "type": "integer" }, "return_on_ad_spend": { "description": "Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.", "example": 6.9, "type": "number" }, "spend": { "description": "Amount charged in dollars in the stats window.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of `spend` and the other monetary metric fields.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ExternalAdStatuses", "description": "Current delivery status of the ad." }, "title": { "description": "The display title of the ad. Falls back to the creative set caption when unset.", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).", "example": 6.9, "type": [ "number", "null" ] }, "unique_clicks": { "description": "Unique clicks (deduplicated by the platform) in the stats window.", "example": 42, "type": "integer" }, "updated_at": { "description": "When the ad was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "title", "status", "platform", "created_at", "updated_at", "issues", "spend", "spend_currency", "impressions", "reach", "clicks", "unique_clicks", "frequency", "click_through_rate", "unique_click_through_rate", "return_on_ad_spend", "purchases", "purchase_value", "leads", "cost_per_click", "cost_per_mille", "cost_per_result", "cost_per_purchase", "cost_per_lead", "ad_group", "ad_campaign" ], "type": "object" }, "AdOrder": { "description": "The fields ad resources can be ordered by.", "enum": [ "created_at", "spend", "return_on_ad_spend" ], "type": "string" }, "AdPlatformIssueCategories": { "description": "Whop's canonical category that a raw platform issue is bucketed into.", "enum": [ "policy_rejection", "creative_media", "audience_targeting", "ad_volume_limit" ], "type": "string" }, "AdPlatformIssueResolutionStatuses": { "description": "The resolution status of an ad platform issue.", "enum": [ "open", "resolved", "acknowledged" ], "type": "string" }, "AdReport": { "description": "An ads performance report. Always returns a summary. The `granularity` field contains a per-bucket time series when the `granularity` arg is set; the `breakdown` field contains per-entity rows when the `breakdown` arg is set.", "properties": { "breakdown": { "description": "Per-entity rows over the date range. `null` when the `breakdown` arg on `adReport` is omitted; otherwise contains one row per ad campaign, ad group, or ad inside the requested scope at the requested level.", "items": { "description": "Per-entity ad performance row. Returned when the `breakdown` arg on `adReport` is set.", "properties": { "granularity": { "description": "Per-bucket time series for this entity over the date range, ordered ascending by `bucketStart`. `null` when the `granularity` arg on `adReport` is omitted; otherwise contains rows at the requested grain (`daily` or `hourly`).", "items": { "description": "Per-bucket ad performance for an ad campaign, ad group, or ad. Bucket grain is set by the `ad_report` query's `granularity` argument.", "properties": { "bucket_start": { "description": "The bucket's start time as a real UTC instant. `(statDate, statHour)` resolved in the ad account's reporting timezone — render this in the viewer's local timezone.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "clicks": { "description": "Clicks in this bucket.", "example": 42, "type": "integer" }, "granularity": { "$ref": "#/components/schemas/Granularities", "description": "The bucket size of this row (`hourly`, `daily`, `weekly`, or `monthly`)." }, "impressions": { "description": "Impressions in this bucket.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in this bucket. Always `0` for hourly rows (Meta does not return reach at hourly grain).", "example": 42, "type": "integer" }, "result_count": { "description": "Count of the primary optimization result in this bucket.", "example": 42, "type": [ "integer", "null" ] }, "result_label_key": { "description": "The type of optimization result represented by `resultCount`.", "oneOf": [ { "$ref": "#/components/schemas/ResultLabelKeys" }, { "type": "null" } ] }, "result_label_override": { "description": "Advertiser-defined label for the result when `resultLabelKey` is `custom`.", "type": [ "string", "null" ] }, "spend": { "description": "Charged spend in this bucket in the requested reporting currency — the amount billed including platform fees, not the platform-side net spend.", "example": 6.9, "type": "number" }, "spend_currency": { "$ref": "#/components/schemas/Currencies", "description": "Currency of the `spend` value." }, "stat_date": { "description": "The date these stats cover (midnight UTC). For hourly rows, see `statHour` and `bucketStart`.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "stat_hour": { "description": "Hour of the day in the ad account's reporting timezone (0-23). `null` for daily rows.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "bucket_start", "stat_date", "stat_hour", "granularity", "spend", "spend_currency", "impressions", "clicks", "reach", "result_count", "result_label_key", "result_label_override" ], "type": "object" }, "type": [ "array", "null" ] }, "id": { "description": "Tag of the entity (ad campaign, ad group, or ad).", "type": "string" }, "level": { "$ref": "#/components/schemas/AdReportBreakdownLevels", "description": "The entity level of this row — matches the `breakdown` arg." }, "name": { "description": "Display name of the entity, when available.", "type": [ "string", "null" ] }, "summary": { "description": "Aggregate totals and rates for this entity over the date range.", "properties": { "click_through_rate": { "description": "Click-through rate (clicks / impressions).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks over the date range.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in the requested reporting currency.", "example": 6.9, "type": "number" }, "cost_per_mille": { "description": "Cost per thousand impressions in the requested reporting currency.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by `resultCount`. Null when there are no results.", "example": 6.9, "type": [ "number", "null" ] }, "frequency": { "description": "Average number of times each reached user saw an ad.", "example": 6.9, "type": [ "number", "null" ] }, "impressions": { "description": "Total impressions over the date range.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached, deduplicated by the external ad platform.", "example": 42, "type": "integer" }, "result_count": { "description": "Count of the campaign's primary optimization result (purchases, clicks, etc.) — see `resultLabelKey`.", "example": 42, "type": [ "integer", "null" ] }, "result_label_key": { "description": "The type of optimization result represented by `resultCount`.", "oneOf": [ { "$ref": "#/components/schemas/ResultLabelKeys" }, { "type": "null" } ] }, "result_label_override": { "description": "Advertiser-defined label for the result when `resultLabelKey` is `custom`.", "type": [ "string", "null" ] }, "return_on_ad_spend": { "description": "Alias for `purchaseReturnOnAdSpend` — return on ad spend for purchases, as reported by the external ad platform.", "example": 6.9, "type": [ "number", "null" ] }, "spend": { "description": "Total spend over the date range in the requested reporting currency.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of the `spend` value. Matches the requested `currency` when set.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] } }, "required": [ "clicks", "impressions", "reach", "spend", "spend_currency", "click_through_rate", "cost_per_click", "cost_per_mille", "frequency", "result_count", "result_label_key", "result_label_override", "cost_per_result", "return_on_ad_spend" ], "type": "object" } }, "required": [ "id", "name", "level", "summary", "granularity" ], "type": "object" }, "type": [ "array", "null" ] }, "granularity": { "description": "Per-bucket time series over the date range, ordered ascending by `bucketStart`. `null` when the `granularity` arg on `adReport` is omitted; otherwise contains rows at the requested grain (`daily` or `hourly`).", "items": { "description": "Per-bucket ad performance for an ad campaign, ad group, or ad. Bucket grain is set by the `ad_report` query's `granularity` argument.", "properties": { "bucket_start": { "description": "The bucket's start time as a real UTC instant. `(statDate, statHour)` resolved in the ad account's reporting timezone — render this in the viewer's local timezone.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "clicks": { "description": "Clicks in this bucket.", "example": 42, "type": "integer" }, "granularity": { "$ref": "#/components/schemas/Granularities", "description": "The bucket size of this row (`hourly`, `daily`, `weekly`, or `monthly`)." }, "impressions": { "description": "Impressions in this bucket.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached in this bucket. Always `0` for hourly rows (Meta does not return reach at hourly grain).", "example": 42, "type": "integer" }, "result_count": { "description": "Count of the primary optimization result in this bucket.", "example": 42, "type": [ "integer", "null" ] }, "result_label_key": { "description": "The type of optimization result represented by `resultCount`.", "oneOf": [ { "$ref": "#/components/schemas/ResultLabelKeys" }, { "type": "null" } ] }, "result_label_override": { "description": "Advertiser-defined label for the result when `resultLabelKey` is `custom`.", "type": [ "string", "null" ] }, "spend": { "description": "Charged spend in this bucket in the requested reporting currency — the amount billed including platform fees, not the platform-side net spend.", "example": 6.9, "type": "number" }, "spend_currency": { "$ref": "#/components/schemas/Currencies", "description": "Currency of the `spend` value." }, "stat_date": { "description": "The date these stats cover (midnight UTC). For hourly rows, see `statHour` and `bucketStart`.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "stat_hour": { "description": "Hour of the day in the ad account's reporting timezone (0-23). `null` for daily rows.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "bucket_start", "stat_date", "stat_hour", "granularity", "spend", "spend_currency", "impressions", "clicks", "reach", "result_count", "result_label_key", "result_label_override" ], "type": "object" }, "type": [ "array", "null" ] }, "summary": { "description": "Aggregate totals and rates over the date range.", "properties": { "click_through_rate": { "description": "Click-through rate (clicks / impressions).", "example": 6.9, "type": "number" }, "clicks": { "description": "Total clicks over the date range.", "example": 42, "type": "integer" }, "cost_per_click": { "description": "Cost per click in the requested reporting currency.", "example": 6.9, "type": "number" }, "cost_per_mille": { "description": "Cost per thousand impressions in the requested reporting currency.", "example": 6.9, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by `resultCount`. Null when there are no results.", "example": 6.9, "type": [ "number", "null" ] }, "frequency": { "description": "Average number of times each reached user saw an ad.", "example": 6.9, "type": [ "number", "null" ] }, "impressions": { "description": "Total impressions over the date range.", "example": 42, "type": "integer" }, "reach": { "description": "Unique users reached, deduplicated by the external ad platform.", "example": 42, "type": "integer" }, "result_count": { "description": "Count of the campaign's primary optimization result (purchases, clicks, etc.) — see `resultLabelKey`.", "example": 42, "type": [ "integer", "null" ] }, "result_label_key": { "description": "The type of optimization result represented by `resultCount`.", "oneOf": [ { "$ref": "#/components/schemas/ResultLabelKeys" }, { "type": "null" } ] }, "result_label_override": { "description": "Advertiser-defined label for the result when `resultLabelKey` is `custom`.", "type": [ "string", "null" ] }, "return_on_ad_spend": { "description": "Alias for `purchaseReturnOnAdSpend` — return on ad spend for purchases, as reported by the external ad platform.", "example": 6.9, "type": [ "number", "null" ] }, "spend": { "description": "Total spend over the date range in the requested reporting currency.", "example": 6.9, "type": "number" }, "spend_currency": { "description": "Currency of the `spend` value. Matches the requested `currency` when set.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] } }, "required": [ "clicks", "impressions", "reach", "spend", "spend_currency", "click_through_rate", "cost_per_click", "cost_per_mille", "frequency", "result_count", "result_label_key", "result_label_override", "cost_per_result", "return_on_ad_spend" ], "type": "object" } }, "required": [ "summary", "granularity", "breakdown" ], "type": "object" }, "AdReportBreakdownLevels": { "description": "Entity level to group an ad report by.", "enum": [ "campaign", "ad_group", "ad" ], "type": "string" }, "Affiliate": { "description": "An affiliate tracks a user's referral performance and commission earnings for a company, including retention rates, revenue metrics, and payout configurations.", "properties": { "active_members_count": { "description": "The total active members of the affiliate", "example": 42, "type": "integer" }, "company": { "description": "The company attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the affiliate was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_retention_rate": { "description": "The percentage of referred customers who are still active members", "type": "string" }, "customer_retention_rate_ninety_days": { "description": "The percentage of referred customers who remained active over the last 90 days", "type": "string" }, "id": { "description": "The unique identifier for the affiliate.", "example": "aff_xxxxxxxxxxxxxx", "type": "string" }, "monthly_recurring_revenue_usd": { "description": "The monthly recurring revenue generated by this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "status": { "description": "The status of the affiliate", "oneOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "total_overrides_count": { "description": "The total count of all overrides for this affiliate", "example": 42, "type": "integer" }, "total_referral_earnings_usd": { "description": "The total commission earnings paid to this affiliate, formatted as a USD currency string", "type": "string" }, "total_referrals_count": { "description": "The total referrals of the affiliate", "example": 42, "type": "integer" }, "total_revenue_usd": { "description": "The total revenue generated from this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "updated_at": { "description": "The datetime the affiliate was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name set on the user's Whop profile. Null if the user has not set a name.", "example": "Jane Smith", "type": [ "string", "null" ] }, "username": { "description": "The unique username chosen by the user for their Whop profile. Null if the user has not set a username.", "example": "janesmith", "type": [ "string", "null" ] } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "created_at", "updated_at", "total_referrals_count", "total_referral_earnings_usd", "total_overrides_count", "customer_retention_rate", "customer_retention_rate_ninety_days", "monthly_recurring_revenue_usd", "total_revenue_usd", "active_members_count", "user", "company" ], "type": "object" }, "AffiliateAppliesToPayments": { "description": "Whether the affiliate commission applies to the first payment or all payments", "enum": [ "first_payment", "all_payments" ], "type": "string" }, "AffiliateAppliesToProducts": { "description": "Whether a rev-share override applies to a single product or all products", "enum": [ "single_product", "all_products" ], "type": "string" }, "AffiliateListItem": { "description": "An affiliate tracks a user's referral performance and commission earnings for a company, including retention rates, revenue metrics, and payout configurations.", "properties": { "active_members_count": { "description": "The total active members of the affiliate", "example": 42, "type": "integer" }, "company": { "description": "The company attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the affiliate was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_retention_rate": { "description": "The percentage of referred customers who are still active members", "type": "string" }, "customer_retention_rate_ninety_days": { "description": "The percentage of referred customers who remained active over the last 90 days", "type": "string" }, "id": { "description": "The unique identifier for the affiliate.", "example": "aff_xxxxxxxxxxxxxx", "type": "string" }, "monthly_recurring_revenue_usd": { "description": "The monthly recurring revenue generated by this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "status": { "description": "The status of the affiliate", "oneOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "total_overrides_count": { "description": "The total count of all overrides for this affiliate", "example": 42, "type": "integer" }, "total_referral_earnings_usd": { "description": "The total commission earnings paid to this affiliate, formatted as a USD currency string", "type": "string" }, "total_referrals_count": { "description": "The total referrals of the affiliate", "example": 42, "type": "integer" }, "total_revenue_usd": { "description": "The total revenue generated from this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "updated_at": { "description": "The datetime the affiliate was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name set on the user's Whop profile. Null if the user has not set a name.", "example": "Jane Smith", "type": [ "string", "null" ] }, "username": { "description": "The unique username chosen by the user for their Whop profile. Null if the user has not set a username.", "example": "janesmith", "type": [ "string", "null" ] } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "created_at", "updated_at", "total_referrals_count", "total_referral_earnings_usd", "total_overrides_count", "customer_retention_rate", "customer_retention_rate_ninety_days", "monthly_recurring_revenue_usd", "total_revenue_usd", "active_members_count", "user", "company" ], "type": "object" }, "AffiliateOverrideRoles": { "description": "The role of an affiliate override (standard or rev_share)", "enum": [ "standard", "rev_share" ], "type": "string" }, "AffiliatePayoutTypes": { "description": "The types of payouts an affiliate can have", "enum": [ "percentage", "flat_fee" ], "type": "string" }, "AffiliateRevenueBases": { "description": "The calculation method for affiliate rev-share percentages", "enum": [ "pre_fees", "post_fees" ], "type": "string" }, "AffiliatesSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at", "cached_total_referrals", "cached_total_rewards" ], "type": "string" }, "AiChat": { "description": "An AI-powered chat conversation belonging to a user, with optional scheduled automation.", "properties": { "blended_token_usage": { "description": "The total number of tokens consumed across all messages in this conversation.", "example": "123.45", "type": "string" }, "created_at": { "description": "The datetime the ai chat was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the ai chat.", "example": "aich_xxxxxxxxxxxxx", "type": "string" }, "last_message_at": { "description": "The timestamp of the most recent message in this conversation. Null if no messages have been sent yet.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "message_count": { "description": "The total number of messages exchanged in this conversation.", "example": 42, "type": "integer" }, "notification_preference": { "$ref": "#/components/schemas/AiChatNotificationPreferences", "description": "The notification preference for this AI chat. `all` delivers AI chat notifications and badges, while `none` mutes them." }, "title": { "description": "A short descriptive title for this AI chat conversation. Null if no title has been set.", "example": "Weekly Revenue Analysis", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the ai chat was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this AI chat conversation.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" } }, "required": [ "id", "title", "notification_preference", "message_count", "blended_token_usage", "created_at", "updated_at", "last_message_at", "user" ], "type": "object" }, "AiChatListItem": { "description": "An AI-powered chat conversation belonging to a user, with optional scheduled automation.", "properties": { "blended_token_usage": { "description": "The total number of tokens consumed across all messages in this conversation.", "example": "123.45", "type": "string" }, "created_at": { "description": "The datetime the ai chat was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the ai chat.", "example": "aich_xxxxxxxxxxxxx", "type": "string" }, "last_message_at": { "description": "The timestamp of the most recent message in this conversation. Null if no messages have been sent yet.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "message_count": { "description": "The total number of messages exchanged in this conversation.", "example": 42, "type": "integer" }, "notification_preference": { "$ref": "#/components/schemas/AiChatNotificationPreferences", "description": "The notification preference for this AI chat. `all` delivers AI chat notifications and badges, while `none` mutes them." }, "title": { "description": "A short descriptive title for this AI chat conversation. Null if no title has been set.", "example": "Weekly Revenue Analysis", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the ai chat was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this AI chat conversation.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" } }, "required": [ "id", "title", "notification_preference", "message_count", "blended_token_usage", "created_at", "updated_at", "last_message_at", "user" ], "type": "object" }, "AiChatMessageSourceTypes": { "description": "The source of an AI chat message", "enum": [ "manual", "suggestion", "link" ], "type": "string" }, "AiChatNotificationPreferences": { "description": "The notification preference for an AI chat", "enum": [ "all", "none" ], "type": "string" }, "ApiVersion": { "description": "The different API versions", "enum": [ "v1", "v2", "v5" ], "type": "string" }, "App": { "description": "An app is an integration built on Whop. Apps can serve consumers as experiences within products, or serve companies as business tools.", "properties": { "api_key": { "description": "The API key used to authenticate requests on behalf of this app. Null if no API key has been generated. Requires the 'developer:manage_api_key' permission.", "properties": { "created_at": { "description": "The datetime the private api key was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the private api key.", "type": "string" }, "token": { "description": "This is the API key used to authenticate requests", "type": "string" } }, "required": [ "id", "token", "created_at" ], "type": [ "object", "null" ] }, "app_type": { "$ref": "#/components/schemas/AppTypes", "description": "The target audience classification for this app (e.g., 'b2b_app', 'b2c_app', 'company_app', 'component')." }, "base_url": { "description": "The production base URL where the app is hosted. Null if no base URL is configured.", "example": "https://myapp.example.com", "type": [ "string", "null" ] }, "company": { "description": "The company that owns and publishes this app.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "creator": { "description": "The user who created and owns the company that published this app.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "dashboard_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "description": { "description": "A written description of what this app does, displayed on the app store listing page. Null if no description has been set.", "example": "A comprehensive analytics dashboard for tracking revenue, members, and growth metrics.", "type": [ "string", "null" ] }, "discover_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "domain_id": { "description": "The unique subdomain identifier for this app's proxied URL on the Whop platform. Forms the URL pattern https://{domain_id}.apps.whop.com.", "example": "ab1c2d3e4f5g6h7i8j9k", "type": "string" }, "experience_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.", "example": "Courses", "type": "string" }, "openapi_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "origin": { "description": "The full origin URL for this app's proxied domain (e.g., 'https://myapp.apps.whop.com'). Null if no proxy domain is configured.", "type": [ "string", "null" ] }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs that users are redirected to after authorizing the app.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "requested_permissions": { "description": "The list of permissions this app requests when installed, including both required and optional permissions with justifications.", "items": { "description": "A permission that the app requests from the admin of a company during the oauth flow.", "properties": { "is_required": { "description": "Whether the action is required for the app to function.", "type": "boolean" }, "justification": { "description": "The reason for requesting the action.", "type": "string" }, "permission_action": { "description": "The action that the app will request off of users when a user installs the app.", "properties": { "action": { "description": "The identifier of the action.", "type": "string" }, "name": { "description": "The human readable name of the action.", "type": "string" } }, "required": [ "action", "name" ], "type": "object" } }, "required": [ "permission_action", "is_required", "justification" ], "type": "object" }, "type": "array" }, "skills_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "stats": { "description": "Aggregate usage statistics for this app, including daily, weekly, and monthly active user counts.", "properties": { "dau": { "description": "The number of unique users who have spent time in this app in the last 24 hours. Returns 0 if no usage data is available.", "example": 42, "type": "integer" }, "mau": { "description": "The number of unique users who have spent time in this app in the last 28 days. Returns 0 if no usage data is available.", "example": 42, "type": "integer" }, "time_spent_last24_hours": { "description": "The total time, in seconds, that all users have spent in this app over the last 24 hours. Returns 0 if no usage data is available.", "example": 42, "type": "integer" }, "wau": { "description": "The number of unique users who have spent time in this app in the last 7 days. Returns 0 if no usage data is available.", "example": 42, "type": "integer" } }, "required": [ "dau", "mau", "time_spent_last24_hours", "wau" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/AppStatuses", "description": "The current visibility status of this app on the Whop app store. 'live' means publicly discoverable, 'unlisted' means accessible only via direct link, and 'hidden' means not visible anywhere." }, "verified": { "description": "Whether this app has been verified by Whop. Verified apps are endorsed by Whop and displayed in the featured apps section of the app store.", "type": "boolean" } }, "required": [ "id", "name", "description", "status", "base_url", "domain_id", "verified", "app_type", "origin", "experience_path", "discover_path", "dashboard_path", "skills_path", "openapi_path", "company", "icon", "creator", "requested_permissions", "stats", "api_key", "redirect_uris" ], "type": "object" }, "AppBuild": { "description": "A versioned build artifact for a Whop React Native App, submitted for review and deployment to a specific platform.", "properties": { "checksum": { "description": "A SHA-256 hash of the uploaded build file, generated by the client and used to verify file integrity.", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "type": "string" }, "created_at": { "description": "The datetime the app build was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "file_url": { "description": "A URL to download the app build as a .zip archive.", "example": "https://cdn.whop.com/builds/abc123.zip", "type": "string" }, "id": { "description": "The unique identifier for the app build.", "example": "apbu_xxxxxxxxxxxxx", "type": "string" }, "is_production": { "description": "Whether this build is the currently active production build for its platform.", "type": "boolean" }, "platform": { "$ref": "#/components/schemas/AppBuildPlatforms", "description": "The target platform for this build." }, "review_message": { "description": "Feedback from the reviewer explaining why the build was rejected. Null if the build has not been reviewed or was approved.", "example": "App crashes on launch. Please fix and resubmit.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AppBuildStatuses", "description": "The current review status of this build." }, "supported_app_view_types": { "description": "The list of view types this build supports, as declared by the developer.", "items": { "$ref": "#/components/schemas/AppViewTypes" }, "type": "array" } }, "required": [ "id", "platform", "file_url", "created_at", "status", "checksum", "supported_app_view_types", "review_message", "is_production" ], "type": "object" }, "AppBuildListItem": { "description": "A versioned build artifact for a Whop React Native App, submitted for review and deployment to a specific platform.", "properties": { "checksum": { "description": "A SHA-256 hash of the uploaded build file, generated by the client and used to verify file integrity.", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "type": "string" }, "created_at": { "description": "The datetime the app build was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "file_url": { "description": "A URL to download the app build as a .zip archive.", "example": "https://cdn.whop.com/builds/abc123.zip", "type": "string" }, "id": { "description": "The unique identifier for the app build.", "example": "apbu_xxxxxxxxxxxxx", "type": "string" }, "is_production": { "description": "Whether this build is the currently active production build for its platform.", "type": "boolean" }, "platform": { "$ref": "#/components/schemas/AppBuildPlatforms", "description": "The target platform for this build." }, "review_message": { "description": "Feedback from the reviewer explaining why the build was rejected. Null if the build has not been reviewed or was approved.", "example": "App crashes on launch. Please fix and resubmit.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AppBuildStatuses", "description": "The current review status of this build." }, "supported_app_view_types": { "description": "The list of view types this build supports, as declared by the developer.", "items": { "$ref": "#/components/schemas/AppViewTypes" }, "type": "array" } }, "required": [ "id", "platform", "file_url", "created_at", "status", "checksum", "supported_app_view_types", "review_message", "is_production" ], "type": "object" }, "AppBuildPlatforms": { "description": "The different platforms an app build can target.", "enum": [ "ios", "android", "web" ], "type": "string" }, "AppBuildStatuses": { "description": "The different statuses an AppBuild can be in.", "enum": [ "draft", "pending", "approved", "rejected" ], "type": "string" }, "AppListItem": { "description": "An app is an integration built on Whop. Apps can serve consumers as experiences within products, or serve companies as business tools.", "properties": { "app_type": { "$ref": "#/components/schemas/AppTypes", "description": "The target audience classification for this app (e.g., 'b2b_app', 'b2c_app', 'company_app', 'component')." }, "base_url": { "description": "The production base URL where the app is hosted. Null if no base URL is configured.", "example": "https://myapp.example.com", "type": [ "string", "null" ] }, "company": { "description": "The company that owns and publishes this app.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "creator": { "description": "The user who created and owns the company that published this app.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "dashboard_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "description": { "description": "A written description of what this app does, displayed on the app store listing page. Null if no description has been set.", "example": "A comprehensive analytics dashboard for tracking revenue, members, and growth metrics.", "type": [ "string", "null" ] }, "discover_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "domain_id": { "description": "The unique subdomain identifier for this app's proxied URL on the Whop platform. Forms the URL pattern https://{domain_id}.apps.whop.com.", "example": "ab1c2d3e4f5g6h7i8j9k", "type": "string" }, "experience_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.", "example": "Courses", "type": "string" }, "openapi_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "origin": { "description": "The full origin URL for this app's proxied domain (e.g., 'https://myapp.apps.whop.com'). Null if no proxy domain is configured.", "type": [ "string", "null" ] }, "skills_path": { "description": "The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/[experienceId]'). Null if the specified view type is not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AppStatuses", "description": "The current visibility status of this app on the Whop app store. 'live' means publicly discoverable, 'unlisted' means accessible only via direct link, and 'hidden' means not visible anywhere." }, "verified": { "description": "Whether this app has been verified by Whop. Verified apps are endorsed by Whop and displayed in the featured apps section of the app store.", "type": "boolean" } }, "required": [ "id", "name", "description", "status", "base_url", "domain_id", "verified", "app_type", "origin", "experience_path", "discover_path", "dashboard_path", "skills_path", "openapi_path", "company", "icon", "creator" ], "type": "object" }, "AppOauthClientTypes": { "description": "How this app authenticates at the OAuth token endpoint.", "enum": [ "public", "confidential" ], "type": "string" }, "AppOrder": { "description": "The order to fetch the apps in for discovery.", "enum": [ "created_at", "discoverable_at", "total_installs_last_30_days", "total_installs_last_7_days", "time_spent", "time_spent_last_24_hours", "daily_active_users", "ai_prompt_count", "total_ai_cost_usd", "total_ai_tokens", "last_ai_prompt_at", "ai_average_rating" ], "type": "string" }, "AppStatuses": { "description": "The status of an experience interface", "enum": [ "live", "unlisted", "hidden" ], "type": "string" }, "AppTypes": { "description": "The type of end-user an app is built for", "enum": [ "b2b_app", "b2c_app", "company_app", "component" ], "type": "string" }, "AppValidScopes": { "const": "read_user", "description": "These are the scopes an app can request on behalf of a user", "type": "string" }, "AppViewTypes": { "description": "The different types of an app view", "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "type": "string" }, "AuthorizedUser": { "description": "A user who has been granted administrative access to manage a company's dashboard and settings.", "properties": { "company": { "description": "The company this authorized user has access to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "id": { "description": "The unique identifier for the authorized user.", "example": "ausr_xxxxxxxxxxxxx", "type": "string" }, "role": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "The permission role assigned to this authorized user within the company." }, "user": { "description": "The user account linked to this authorized user record.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "role", "user", "company" ], "type": "object" }, "AuthorizedUserListItem": { "description": "A user who has been granted administrative access to manage a company's dashboard and settings.", "properties": { "company": { "description": "The company this authorized user has access to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "id": { "description": "The unique identifier for the authorized user.", "example": "ausr_xxxxxxxxxxxxx", "type": "string" }, "role": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "The permission role assigned to this authorized user within the company." }, "user": { "description": "The user account linked to this authorized user record.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "role", "user", "company" ], "type": "object" }, "AuthorizedUserRoles": { "description": "Possible roles an authorized user can have", "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "custom" ], "type": "string" }, "BillingReasons": { "description": "The reason why a specific payment was billed", "enum": [ "subscription_create", "subscription_cycle", "subscription_update", "one_time", "manual", "subscription" ], "type": "string" }, "Bounty": { "description": "A privately accessible bounty.", "properties": { "bounty_type": { "$ref": "#/components/schemas/BountyTypes", "description": "The underlying bounty implementation type." }, "created_at": { "description": "The datetime the bounty was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for the bounty funds." }, "description": { "description": "The description of the bounty.", "type": "string" }, "id": { "description": "The unique identifier for the bounty.", "example": "bnty_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/Statuses", "description": "The current lifecycle status of the bounty." }, "title": { "description": "The title of the bounty.", "type": "string" }, "total_available": { "description": "The total amount currently funded in the bounty pool for payout.", "example": 6.9, "type": "number" }, "total_paid": { "description": "The total amount paid out for this bounty.", "example": 6.9, "type": "number" }, "updated_at": { "description": "The datetime the bounty was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "vote_threshold": { "description": "The number of watcher votes required before the submission can resolve.", "example": 42, "type": "integer" } }, "required": [ "id", "title", "description", "status", "total_available", "total_paid", "currency", "bounty_type", "vote_threshold", "created_at", "updated_at" ], "type": "object" }, "BountyListItem": { "description": "A privately accessible bounty.", "properties": { "bounty_type": { "$ref": "#/components/schemas/BountyTypes", "description": "The underlying bounty implementation type." }, "created_at": { "description": "The datetime the bounty was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for the bounty funds." }, "description": { "description": "The description of the bounty.", "type": "string" }, "id": { "description": "The unique identifier for the bounty.", "example": "bnty_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/Statuses", "description": "The current lifecycle status of the bounty." }, "title": { "description": "The title of the bounty.", "type": "string" }, "total_available": { "description": "The total amount currently funded in the bounty pool for payout.", "example": 6.9, "type": "number" }, "total_paid": { "description": "The total amount paid out for this bounty.", "example": 6.9, "type": "number" }, "updated_at": { "description": "The datetime the bounty was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "vote_threshold": { "description": "The number of watcher votes required before the submission can resolve.", "example": 42, "type": "integer" } }, "required": [ "id", "title", "description", "status", "total_available", "total_paid", "currency", "bounty_type", "vote_threshold", "created_at", "updated_at" ], "type": "object" }, "BountyTypes": { "description": "The available bounty implementation types.", "enum": [ "classic", "user_funded", "workforce" ], "type": "string" }, "CancelOptions": { "description": "The different reasons a user can choose for why they are canceling their membership.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "other", "testing" ], "type": "string" }, "CardBrands": { "description": "Possible card brands that a payment token can have", "enum": [ "mastercard", "visa", "amex", "discover", "unionpay", "jcb", "diners", "link", "troy", "visadankort", "visabancontact", "china_union_pay", "rupay", "jcbrupay", "elo", "maestro", "tarjeta_naranja", "cirrus", "nspk_mir", "verve", "ebt", "private_label", "local_brand", "uatp", "wexcard", "uzcard", "meeza", "hrg_store_card", "girocard", "fuel_card", "dankort", "carnet", "atm_card", "china_union_payuzcard", "codensa", "cabal", "hipercard", "jcblankapay", "cmi", "unknown" ], "type": "string" }, "CardIssuingTransactionStatus": { "description": "The lifecycle status of a card transaction.", "enum": [ "pending", "completed", "reversed", "declined" ], "type": "string" }, "CardTransaction": { "description": "A card transaction record.", "properties": { "authorization_method": { "description": "How the card was presented or authenticated for the purchase.", "example": "ecommerce", "type": [ "string", "null" ] }, "card_id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "cashback_usd_amount": { "description": "The cashback reward amount earned on this transaction, in USD.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "The datetime the card transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The ISO 4217 currency code for the transaction amount.", "example": "USD", "type": [ "string", "null" ] }, "declined_reason": { "description": "The issuer-provided reason the transaction was declined.", "example": "insufficient_funds", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the card transaction.", "type": "string" }, "international": { "description": "Whether the transaction was made with a merchant outside the card's home country.", "type": "boolean" }, "local_amount": { "description": "The transaction amount in the merchant's local currency before conversion.", "example": 6.9, "type": [ "number", "null" ] }, "memo": { "description": "A user-provided note attached to the transaction.", "example": "Team dinner", "type": [ "string", "null" ] }, "merchant_category": { "description": "The enriched or raw category label for the merchant.", "example": "Software", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "The four-digit ISO 18245 merchant category code (MCC).", "example": "5734", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "A URL to the enriched merchant logo image.", "example": "https://logo.clearbit.com/example.com", "type": [ "string", "null" ] }, "merchant_name": { "description": "The enriched or raw name of the merchant where the purchase was made.", "example": "Acme Corporation", "type": [ "string", "null" ] }, "posted_at": { "description": "When the transaction was settled by the card network.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CardIssuingTransactionStatus", "description": "The current lifecycle status of the transaction." }, "transaction_type": { "description": "The type of transaction.", "example": "spend", "type": "string" }, "usd_amount": { "description": "The transaction amount in USD.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "id", "usd_amount", "authorization_method", "created_at", "card_id", "cashback_usd_amount", "currency", "declined_reason", "international", "local_amount", "memo", "merchant_category", "merchant_category_code", "merchant_icon_url", "merchant_name", "posted_at", "status", "transaction_type" ], "type": "object" }, "CardTransactionListItem": { "description": "A card transaction record.", "properties": { "authorization_method": { "description": "How the card was presented or authenticated for the purchase.", "example": "ecommerce", "type": [ "string", "null" ] }, "card_id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "cashback_usd_amount": { "description": "The cashback reward amount earned on this transaction, in USD.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "The datetime the card transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The ISO 4217 currency code for the transaction amount.", "example": "USD", "type": [ "string", "null" ] }, "declined_reason": { "description": "The issuer-provided reason the transaction was declined.", "example": "insufficient_funds", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the card transaction.", "type": "string" }, "international": { "description": "Whether the transaction was made with a merchant outside the card's home country.", "type": "boolean" }, "local_amount": { "description": "The transaction amount in the merchant's local currency before conversion.", "example": 6.9, "type": [ "number", "null" ] }, "memo": { "description": "A user-provided note attached to the transaction.", "example": "Team dinner", "type": [ "string", "null" ] }, "merchant_category": { "description": "The enriched or raw category label for the merchant.", "example": "Software", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "The four-digit ISO 18245 merchant category code (MCC).", "example": "5734", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "A URL to the enriched merchant logo image.", "example": "https://logo.clearbit.com/example.com", "type": [ "string", "null" ] }, "merchant_name": { "description": "The enriched or raw name of the merchant where the purchase was made.", "example": "Acme Corporation", "type": [ "string", "null" ] }, "posted_at": { "description": "When the transaction was settled by the card network.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CardIssuingTransactionStatus", "description": "The current lifecycle status of the transaction." }, "transaction_type": { "description": "The type of transaction.", "example": "spend", "type": "string" }, "usd_amount": { "description": "The transaction amount in USD.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "id", "usd_amount", "authorization_method", "created_at", "card_id", "cashback_usd_amount", "currency", "declined_reason", "international", "local_amount", "memo", "merchant_category", "merchant_category_code", "merchant_icon_url", "merchant_name", "posted_at", "status", "transaction_type" ], "type": "object" }, "ChatChannel": { "description": "A real-time chat feed attached to an experience, with configurable moderation and posting permissions.", "properties": { "ban_media": { "description": "Whether media uploads such as images and videos are blocked in this chat.", "type": "boolean" }, "ban_urls": { "description": "Whether URL links are blocked from being posted in this chat.", "type": "boolean" }, "banned_words": { "description": "A list of words that are automatically filtered from messages in this chat.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "experience": { "description": "The experience this chat feed is attached to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "user_posts_cooldown_seconds": { "description": "The minimum number of seconds a user must wait between consecutive messages. Null if no cooldown is enforced.", "example": 42, "type": [ "integer", "null" ] }, "who_can_post": { "$ref": "#/components/schemas/WhoCanPostTypes", "description": "The permission level controlling which users can send messages in this chat." }, "who_can_react": { "$ref": "#/components/schemas/WhoCanReactTypes", "description": "The permission level controlling which users can add reactions in this chat." } }, "required": [ "id", "experience", "ban_media", "ban_urls", "who_can_post", "who_can_react", "user_posts_cooldown_seconds", "banned_words" ], "type": "object" }, "ChatChannelListItem": { "description": "A real-time chat feed attached to an experience, with configurable moderation and posting permissions.", "properties": { "ban_media": { "description": "Whether media uploads such as images and videos are blocked in this chat.", "type": "boolean" }, "ban_urls": { "description": "Whether URL links are blocked from being posted in this chat.", "type": "boolean" }, "banned_words": { "description": "A list of words that are automatically filtered from messages in this chat.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "experience": { "description": "The experience this chat feed is attached to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "user_posts_cooldown_seconds": { "description": "The minimum number of seconds a user must wait between consecutive messages. Null if no cooldown is enforced.", "example": 42, "type": [ "integer", "null" ] }, "who_can_post": { "$ref": "#/components/schemas/WhoCanPostTypes", "description": "The permission level controlling which users can send messages in this chat." }, "who_can_react": { "$ref": "#/components/schemas/WhoCanReactTypes", "description": "The permission level controlling which users can add reactions in this chat." } }, "required": [ "id", "experience", "ban_media", "ban_urls", "who_can_post", "who_can_react", "user_posts_cooldown_seconds", "banned_words" ], "type": "object" }, "CheckoutConfiguration": { "description": "A checkout configuration is a reusable configuration for a checkout, including the plan, affiliate, and custom metadata. Payments and memberships created from a checkout session inherit its metadata.", "properties": { "affiliate_code": { "description": "The affiliate code to use for the checkout configuration", "type": [ "string", "null" ] }, "allow_promo_codes": { "description": "Whether the checkout configuration allows promo codes. When false, the promo code input is hidden and promo codes are rejected.", "type": "boolean" }, "company_id": { "description": "The ID of the company to use for the checkout configuration", "type": "string" }, "currency": { "description": "The currency to use for the configuration when in 'setup' mode. This is used to target which currency specific payment methods are available. If not provided, it will default to 'usd' when in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "The metadata to use for the checkout configuration", "type": [ "object", "null" ] }, "mode": { "$ref": "#/components/schemas/CheckoutModes", "description": "The mode of the checkout session." }, "payment_method_configuration": { "description": "The explicit payment method configuration for the session, if any. This currently only works in 'setup' mode. Use the plan's payment_method_configuration for payment method.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": "boolean" } }, "required": [ "enabled", "disabled", "include_platform_defaults" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan to use for the checkout configuration", "properties": { "adaptive_pricing_enabled": { "description": "Whether the creator has turned on adaptive pricing for this plan. Raw setting — does not check processor compatibility or feature flags.", "type": "boolean" }, "billing_period": { "description": "The number of days between each recurring charge. Null for one-time plans. For example, 30 for monthly or 365 for annual billing.", "example": 42, "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "expiration_days": { "description": "The number of days until the membership expires (for expiration-based plans). For example, 365 for a one-year access pass.", "example": 42, "type": [ "integer", "null" ] }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's base_currency (e.g., 49.99 for $49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal_price.", "example": 6.9, "type": "number" }, "plan_type": { "$ref": "#/components/schemas/PlanTypes", "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments." }, "release_method": { "$ref": "#/components/schemas/ReleaseMethod", "description": "The method used to sell this plan: 'buy_now' for immediate purchase or 'waitlist' for waitlist-based access." }, "renewal_price": { "description": "The recurring price charged every billing_period in the plan's base_currency (e.g., 9.99 for $9.99/period). Zero for one-time plans.", "example": 6.9, "type": "number" }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Null means the plan inherits the account default.", "oneOf": [ { "$ref": "#/components/schemas/PlanThreeDsLevels" }, { "type": "null" } ] }, "trial_period_days": { "description": "The number of free trial days before the first charge on a renewal plan. Null if no trial is configured or the current user has already used a trial for this plan.", "example": 42, "type": [ "integer", "null" ] }, "visibility": { "$ref": "#/components/schemas/Visibility", "description": "Controls whether the plan is visible to customers. When set to 'hidden', the plan is only accessible via direct link." } }, "required": [ "id", "visibility", "plan_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": [ "object", "null" ] }, "purchase_url": { "description": "A URL you can send to customers to complete a checkout. It looks like `/checkout/plan_xxxx?session={id}`", "type": "string" }, "redirect_url": { "description": "The URL to redirect the user to after the checkout configuration is created", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "mode", "currency", "plan", "affiliate_code", "metadata", "redirect_url", "purchase_url", "allow_promo_codes", "payment_method_configuration" ], "type": "object" }, "CheckoutConfigurationListItem": { "description": "A checkout configuration is a reusable configuration for a checkout, including the plan, affiliate, and custom metadata. Payments and memberships created from a checkout session inherit its metadata.", "properties": { "affiliate_code": { "description": "The affiliate code to use for the checkout configuration", "type": [ "string", "null" ] }, "allow_promo_codes": { "description": "Whether the checkout configuration allows promo codes. When false, the promo code input is hidden and promo codes are rejected.", "type": "boolean" }, "company_id": { "description": "The ID of the company to use for the checkout configuration", "type": "string" }, "currency": { "description": "The currency to use for the configuration when in 'setup' mode. This is used to target which currency specific payment methods are available. If not provided, it will default to 'usd' when in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "The metadata to use for the checkout configuration", "type": [ "object", "null" ] }, "mode": { "$ref": "#/components/schemas/CheckoutModes", "description": "The mode of the checkout session." }, "payment_method_configuration": { "description": "The explicit payment method configuration for the session, if any. This currently only works in 'setup' mode. Use the plan's payment_method_configuration for payment method.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": "boolean" } }, "required": [ "enabled", "disabled", "include_platform_defaults" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan to use for the checkout configuration", "properties": { "adaptive_pricing_enabled": { "description": "Whether the creator has turned on adaptive pricing for this plan. Raw setting — does not check processor compatibility or feature flags.", "type": "boolean" }, "billing_period": { "description": "The number of days between each recurring charge. Null for one-time plans. For example, 30 for monthly or 365 for annual billing.", "example": 42, "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "expiration_days": { "description": "The number of days until the membership expires (for expiration-based plans). For example, 365 for a one-year access pass.", "example": 42, "type": [ "integer", "null" ] }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's base_currency (e.g., 49.99 for $49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal_price.", "example": 6.9, "type": "number" }, "plan_type": { "$ref": "#/components/schemas/PlanTypes", "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments." }, "release_method": { "$ref": "#/components/schemas/ReleaseMethod", "description": "The method used to sell this plan: 'buy_now' for immediate purchase or 'waitlist' for waitlist-based access." }, "renewal_price": { "description": "The recurring price charged every billing_period in the plan's base_currency (e.g., 9.99 for $9.99/period). Zero for one-time plans.", "example": 6.9, "type": "number" }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Null means the plan inherits the account default.", "oneOf": [ { "$ref": "#/components/schemas/PlanThreeDsLevels" }, { "type": "null" } ] }, "trial_period_days": { "description": "The number of free trial days before the first charge on a renewal plan. Null if no trial is configured or the current user has already used a trial for this plan.", "example": 42, "type": [ "integer", "null" ] }, "visibility": { "$ref": "#/components/schemas/Visibility", "description": "Controls whether the plan is visible to customers. When set to 'hidden', the plan is only accessible via direct link." } }, "required": [ "id", "visibility", "plan_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": [ "object", "null" ] }, "purchase_url": { "description": "A URL you can send to customers to complete a checkout. It looks like `/checkout/plan_xxxx?session={id}`", "type": "string" }, "redirect_url": { "description": "The URL to redirect the user to after the checkout configuration is created", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "mode", "currency", "plan", "affiliate_code", "metadata", "redirect_url", "purchase_url", "allow_promo_codes", "payment_method_configuration" ], "type": "object" }, "CheckoutFonts": { "description": "The different font families available for checkout pages.", "enum": [ "system", "roboto", "open_sans" ], "type": "string" }, "CheckoutModes": { "description": "The different modes a checkout can be set to.", "enum": [ "payment", "setup" ], "type": "string" }, "CheckoutShapes": { "description": "The different border-radius styles available for checkout pages.", "enum": [ "rounded", "pill", "rectangular" ], "type": "string" }, "Company": { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "affiliate_instructions": { "description": "Guidelines and instructions provided to affiliates explaining how to promote this company's products.", "example": "Share your unique link on social media to earn 20% commission.", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the company was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "A promotional pitch written by the company creator, displayed to potential customers on the store page.", "example": "Learn the fundamentals of data analytics with hands-on projects.", "type": [ "string", "null" ] }, "featured_affiliate_product": { "description": "The product featured for affiliates to promote on this company's affiliate page. Null if none is configured.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the product shown to customers. Maximum 50 characters.", "type": "string" } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo": { "description": "The company's logo.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "member_count": { "description": "The total number of users who currently hold active memberships across all of this company's products.", "example": 42, "type": "integer" }, "metadata": { "additionalProperties": true, "description": "A key-value JSON object of custom metadata for this company, managed by the platform that created the account.", "type": [ "object", "null" ] }, "owner_user": { "description": "The user who owns and has full administrative control over this company.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "published_reviews_count": { "description": "The total number of published customer reviews across all products for this company.", "example": 42, "type": "integer" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "send_customer_emails": { "description": "Whether Whop sends transactional emails (receipts, updates) to customers on behalf of this company.", "type": "boolean" }, "social_links": { "description": "The list of social media accounts and external links associated with this company.", "items": { "description": "A social link attached to a resource on the site.", "properties": { "id": { "description": "The unique identifier for the social link.", "example": "soci_xxxxxxxxxxxxx", "type": "string" }, "url": { "description": "The URL of the social media profile or external link.", "example": "https://x.com/whop", "type": "string" }, "website": { "$ref": "#/components/schemas/SocialLinkWebsites", "description": "The website" } }, "required": [ "id", "url", "website" ], "type": "object" }, "type": "array" }, "target_audience": { "description": "The target audience for the company. Null if not set.", "type": [ "string", "null" ] }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" }, "updated_at": { "description": "The datetime the company was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verified": { "description": "Whether this company has been verified by Whop's trust and safety team.", "type": "boolean" } }, "required": [ "id", "title", "description", "verified", "send_customer_emails", "created_at", "updated_at", "member_count", "owner_user", "route", "logo", "published_reviews_count", "metadata", "target_audience", "social_links", "affiliate_instructions", "featured_affiliate_product" ], "type": "object" }, "CompanyListItem": { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "created_at": { "description": "The datetime the company was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "A promotional pitch written by the company creator, displayed to potential customers on the store page.", "example": "Learn the fundamentals of data analytics with hands-on projects.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo": { "description": "The company's logo.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "member_count": { "description": "The total number of users who currently hold active memberships across all of this company's products.", "example": 42, "type": "integer" }, "metadata": { "additionalProperties": true, "description": "A key-value JSON object of custom metadata for this company, managed by the platform that created the account.", "type": [ "object", "null" ] }, "owner_user": { "description": "The user who owns and has full administrative control over this company.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "published_reviews_count": { "description": "The total number of published customer reviews across all products for this company.", "example": 42, "type": "integer" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "send_customer_emails": { "description": "Whether Whop sends transactional emails (receipts, updates) to customers on behalf of this company.", "type": "boolean" }, "target_audience": { "description": "The target audience for the company. Null if not set.", "type": [ "string", "null" ] }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" }, "updated_at": { "description": "The datetime the company was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verified": { "description": "Whether this company has been verified by Whop's trust and safety team.", "type": "boolean" } }, "required": [ "id", "title", "description", "verified", "send_customer_emails", "created_at", "updated_at", "member_count", "owner_user", "route", "logo", "published_reviews_count", "metadata", "target_audience" ], "type": "object" }, "CompanyTokenTransaction": { "description": "A token transaction records a credit or debit to a member's token balance within a company, including transfers between members.", "properties": { "amount": { "description": "The token amount for this transaction. Always a positive value regardless of transaction type.", "example": 6.9, "type": "number" }, "company": { "description": "The company whose token balance this transaction affects.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the company token transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "Free-text description explaining the reason for this token transaction. Null if no description was provided.", "example": "Reward for completing onboarding", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company token transaction.", "type": "string" }, "idempotency_key": { "description": "A unique key used to prevent duplicate transactions when retrying API requests. Null if no idempotency key was provided.", "example": "txn_reward_usr_123_2024", "type": [ "string", "null" ] }, "linked_transaction_id": { "description": "The ID of the corresponding transaction on the other side of a transfer. Null if this is not a transfer transaction.", "type": [ "string", "null" ] }, "member": { "description": "The member whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "transaction_type": { "$ref": "#/components/schemas/CompanyTokenTransactionTypes", "description": "The direction of this token transaction (add, subtract, or transfer)." }, "user": { "description": "The user whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "transaction_type", "amount", "description", "created_at", "linked_transaction_id", "idempotency_key", "user", "member", "company" ], "type": "object" }, "CompanyTokenTransactionListItem": { "description": "A token transaction records a credit or debit to a member's token balance within a company, including transfers between members.", "properties": { "amount": { "description": "The token amount for this transaction. Always a positive value regardless of transaction type.", "example": 6.9, "type": "number" }, "company": { "description": "The company whose token balance this transaction affects.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the company token transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "Free-text description explaining the reason for this token transaction. Null if no description was provided.", "example": "Reward for completing onboarding", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company token transaction.", "type": "string" }, "idempotency_key": { "description": "A unique key used to prevent duplicate transactions when retrying API requests. Null if no idempotency key was provided.", "example": "txn_reward_usr_123_2024", "type": [ "string", "null" ] }, "linked_transaction_id": { "description": "The ID of the corresponding transaction on the other side of a transfer. Null if this is not a transfer transaction.", "type": [ "string", "null" ] }, "member": { "description": "The member whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "transaction_type": { "$ref": "#/components/schemas/CompanyTokenTransactionTypes", "description": "The direction of this token transaction (add, subtract, or transfer)." }, "user": { "description": "The user whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "transaction_type", "amount", "description", "created_at", "linked_transaction_id", "idempotency_key", "user", "member", "company" ], "type": "object" }, "CompanyTokenTransactionTypes": { "description": "The type of token transaction", "enum": [ "add", "subtract", "transfer" ], "type": "string" }, "Course": { "description": "A structured learning module containing chapters and lessons, belonging to an experience.", "properties": { "certificate_after_completion_enabled": { "description": "Whether students receive a PDF certificate after completing all lessons in this course. Null if the setting has not been configured.", "type": [ "boolean", "null" ] }, "chapters": { "description": "An ordered list of all chapters in this course, sorted by their display position.", "items": { "description": "A grouping of related lessons within a course, used to organize content into sections.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "lessons": { "description": "An ordered list of lessons in this chapter, sorted by display position. Hidden lessons are excluded for non-admin users.", "items": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge_check." }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "thumbnail": { "description": "The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" }, "video_asset": { "description": "The Mux video asset for video-type lessons, used for streaming playback. Null if this lesson has no hosted video.", "properties": { "duration_seconds": { "description": "The duration of the video in seconds", "example": 42, "type": [ "integer", "null" ] }, "signed_playback_id": { "description": "The signed playback ID of the Mux asset", "type": [ "string", "null" ] }, "signed_thumbnail_playback_token": { "description": "The signed thumbnail playback token of the Mux asset", "type": [ "string", "null" ] } }, "required": [ "signed_playback_id", "signed_thumbnail_playback_token", "duration_seconds" ], "type": [ "object", "null" ] } }, "required": [ "id", "lesson_type", "title", "order", "video_asset", "thumbnail" ], "type": "object" }, "type": "array" }, "order": { "description": "The sort position of this chapter within its parent course, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the chapter shown to students. Maximum 150 characters.", "example": "Getting Started", "type": "string" } }, "required": [ "id", "title", "order", "lessons" ], "type": "object" }, "type": "array" }, "cover_image": { "description": "The URL of the course cover image shown on preview cards. Null if no cover image has been uploaded.", "example": "https://assets.whop.com/images/course-cover.jpg", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the course was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "A brief summary of the course content and objectives. Null if no description has been set.", "example": "Learn advanced trading strategies from industry experts.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "language": { "$ref": "#/components/schemas/Languages", "description": "The spoken language of the video content, used to generate accurate closed captions. One of: en, es, it, pt, de, fr, pl, ru, nl, ca, tr, sv, uk, no, fi, sk, el, cs, hr, da, ro, bg." }, "order": { "description": "The sort position of this course within its parent experience, as a decimal for flexible ordering.", "example": "123.45", "type": "string" }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": "boolean" }, "tagline": { "description": "A short marketing tagline displayed beneath the course title. Null if no tagline has been set.", "example": "Master the fundamentals in 30 days", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image displayed on course cards and previews. Null if no thumbnail has been uploaded.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "optimized_url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] }, "source_url": { "description": "The original source URL of the attachment, such as a direct link to S3. This should never be displayed on the client and should always be passed through an Imgproxy transformer.", "example": "https://media.whop.com/abc123/original.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "optimized_url", "source_url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the course was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "visibility": { "$ref": "#/components/schemas/CourseVisibilities", "description": "The visibility setting that controls whether this course appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "tagline", "cover_image", "thumbnail", "description", "language", "certificate_after_completion_enabled", "require_completing_lessons_in_order", "order", "visibility", "created_at", "updated_at", "chapters" ], "type": "object" }, "CourseChapter": { "description": "A grouping of related lessons within a course, used to organize content into sections.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "lessons": { "description": "An ordered list of lessons in this chapter, sorted by display position. Hidden lessons are excluded for non-admin users.", "items": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title", "order" ], "type": "object" }, "type": "array" }, "order": { "description": "The sort position of this chapter within its parent course, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the chapter shown to students. Maximum 150 characters.", "example": "Getting Started", "type": "string" } }, "required": [ "id", "title", "order", "lessons" ], "type": "object" }, "CourseChapterListItem": { "description": "A grouping of related lessons within a course, used to organize content into sections.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "order": { "description": "The sort position of this chapter within its parent course, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the chapter shown to students. Maximum 150 characters.", "example": "Getting Started", "type": "string" } }, "required": [ "id", "title", "order" ], "type": "object" }, "CourseLesson": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "assessment_questions": { "description": "The list of questions for quiz or knowledge check lessons. Empty for non-assessment lesson types.", "items": { "description": "An assessment question in a course quiz or knowledge check", "properties": { "correct_answer": { "description": "The correct answer for the question. Used for short answer questions. Only visible to admins (users with courses:update permission)", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the assessment question was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the assessment question.", "example": "crsaq_xxxxxxxxxxxx", "type": "string" }, "image": { "description": "Optional image attachment for the question", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "options": { "description": "The answer options for multiple choice/select questions", "items": { "description": "An answer option for a multiple choice or multiple select assessment question", "properties": { "id": { "description": "The unique identifier for the assessment question option.", "example": "crsaqo_xxxxxxxxxxx", "type": "string" }, "is_correct": { "description": "Whether this option is a correct answer. Only visible to admins (users with courses:update permission)", "type": [ "boolean", "null" ] }, "option_text": { "description": "The text of the answer option", "type": "string" }, "order": { "description": "The order of this option within the question", "example": 42, "type": "integer" } }, "required": [ "id", "option_text", "is_correct", "order" ], "type": "object" }, "type": "array" }, "order": { "description": "The order of the question within its lesson", "example": 42, "type": "integer" }, "question_text": { "description": "The text of the question", "type": "string" }, "question_type": { "$ref": "#/components/schemas/CoursesAssessmentQuestionTypes", "description": "The type of the question" } }, "required": [ "id", "question_text", "question_type", "correct_answer", "order", "created_at", "image", "options" ], "type": "object" }, "type": "array" }, "attachments": { "description": "All supplementary files attached to this lesson returned as a flat array rather than a paginated connection.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "content": { "description": "The Markdown content body of the lesson. Null if the lesson has no text content.", "example": "In this lesson, we will cover the basics of technical analysis...", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the lesson was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible. Null if the lesson is available immediately.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded video lessons, such as a YouTube video ID or Loom share ID. Null if the lesson has no embed.", "example": "dQw4w9WgXcQ", "type": [ "string", "null" ] }, "embed_type": { "description": "The platform type for the embedded video. One of: youtube, loom. Null if the lesson has no embed.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge_check." }, "main_pdf": { "description": "The primary PDF document for PDF-type lessons. Null if this lesson is not a PDF lesson or no PDF has been uploaded.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "thumbnail": { "description": "The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" }, "video_asset": { "description": "The Mux video asset for video-type lessons, used for streaming playback. Null if this lesson has no hosted video.", "properties": { "asset_id": { "description": "The Mux-provided ID of the asset", "type": [ "string", "null" ] }, "audio_only": { "description": "Whether this asset contains only audio", "type": "boolean" }, "created_at": { "description": "The datetime the mux asset was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "duration_seconds": { "description": "The duration of the video in seconds", "example": 42, "type": [ "integer", "null" ] }, "finished_uploading_at": { "description": "The time at which the video finished uploading", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the mux asset.", "example": "mux_xxxxxxxxxxxxxx", "type": "string" }, "playback_id": { "description": "The public playback ID of the Mux asset", "type": [ "string", "null" ] }, "signed_playback_id": { "description": "The signed playback ID of the Mux asset", "type": [ "string", "null" ] }, "signed_storyboard_playback_token": { "description": "The signed storyboard playback token of the Mux asset", "type": [ "string", "null" ] }, "signed_thumbnail_playback_token": { "description": "The signed thumbnail playback token of the Mux asset", "type": [ "string", "null" ] }, "signed_video_playback_token": { "description": "The signed video playback token of the Mux asset", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MuxAssetStatuses", "description": "The status of the Mux asset" }, "updated_at": { "description": "The datetime the mux asset was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "asset_id", "playback_id", "signed_playback_id", "status", "audio_only", "duration_seconds", "signed_video_playback_token", "signed_thumbnail_playback_token", "signed_storyboard_playback_token", "created_at", "updated_at", "finished_uploading_at" ], "type": [ "object", "null" ] }, "visibility": { "$ref": "#/components/schemas/LessonVisibilities", "description": "The visibility setting that controls whether this lesson appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "order", "lesson_type", "visibility", "content", "days_from_course_start_until_unlock", "embed_type", "embed_id", "created_at", "thumbnail", "video_asset", "main_pdf", "assessment_questions", "attachments" ], "type": "object" }, "CourseLessonInteraction": { "description": "A record of a user's progress on a specific lesson, tracking whether they have completed it.", "properties": { "completed": { "description": "Whether the user has finished this lesson.", "type": "boolean" }, "course": { "description": "The course that contains the tracked lesson.", "properties": { "experience": { "description": "The parent experience that this course belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] } }, "required": [ "id", "title", "experience" ], "type": "object" }, "created_at": { "description": "The datetime the lesson interaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lesson interaction.", "example": "crsli_xxxxxxxxxxxx", "type": "string" }, "lesson": { "description": "The lesson that this progress record belongs to.", "properties": { "chapter": { "description": "The parent chapter that contains this lesson.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title", "chapter" ], "type": "object" }, "user": { "description": "The user whose progress is being tracked.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed", "created_at", "lesson", "user", "course" ], "type": "object" }, "CourseLessonInteractionListItem": { "description": "A record of a user's progress on a specific lesson, tracking whether they have completed it.", "properties": { "completed": { "description": "Whether the user has finished this lesson.", "type": "boolean" }, "created_at": { "description": "The datetime the lesson interaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lesson interaction.", "example": "crsli_xxxxxxxxxxxx", "type": "string" }, "lesson": { "description": "The lesson that this progress record belongs to.", "properties": { "chapter": { "description": "The parent chapter that contains this lesson.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title", "chapter" ], "type": "object" }, "user": { "description": "The user whose progress is being tracked.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed", "created_at", "lesson", "user" ], "type": "object" }, "CourseLessonListItem": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "content": { "description": "The Markdown content body of the lesson. Null if the lesson has no text content.", "example": "In this lesson, we will cover the basics of technical analysis...", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the lesson was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible. Null if the lesson is available immediately.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded video lessons, such as a YouTube video ID or Loom share ID. Null if the lesson has no embed.", "example": "dQw4w9WgXcQ", "type": [ "string", "null" ] }, "embed_type": { "description": "The platform type for the embedded video. One of: youtube, loom. Null if the lesson has no embed.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge_check." }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "thumbnail": { "description": "The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" }, "visibility": { "$ref": "#/components/schemas/LessonVisibilities", "description": "The visibility setting that controls whether this lesson appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "order", "lesson_type", "visibility", "content", "days_from_course_start_until_unlock", "embed_type", "embed_id", "created_at", "thumbnail" ], "type": "object" }, "CourseListItem": { "description": "A structured learning module containing chapters and lessons, belonging to an experience.", "properties": { "certificate_after_completion_enabled": { "description": "Whether students receive a PDF certificate after completing all lessons in this course. Null if the setting has not been configured.", "type": [ "boolean", "null" ] }, "cover_image": { "description": "The URL of the course cover image shown on preview cards. Null if no cover image has been uploaded.", "example": "https://assets.whop.com/images/course-cover.jpg", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the course was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "A brief summary of the course content and objectives. Null if no description has been set.", "example": "Learn advanced trading strategies from industry experts.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "language": { "$ref": "#/components/schemas/Languages", "description": "The spoken language of the video content, used to generate accurate closed captions. One of: en, es, it, pt, de, fr, pl, ru, nl, ca, tr, sv, uk, no, fi, sk, el, cs, hr, da, ro, bg." }, "order": { "description": "The sort position of this course within its parent experience, as a decimal for flexible ordering.", "example": "123.45", "type": "string" }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": "boolean" }, "tagline": { "description": "A short marketing tagline displayed beneath the course title. Null if no tagline has been set.", "example": "Master the fundamentals in 30 days", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image displayed on course cards and previews. Null if no thumbnail has been uploaded.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "optimized_url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] }, "source_url": { "description": "The original source URL of the attachment, such as a direct link to S3. This should never be displayed on the client and should always be passed through an Imgproxy transformer.", "example": "https://media.whop.com/abc123/original.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "optimized_url", "source_url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the course was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "visibility": { "$ref": "#/components/schemas/CourseVisibilities", "description": "The visibility setting that controls whether this course appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "tagline", "cover_image", "thumbnail", "description", "language", "certificate_after_completion_enabled", "require_completing_lessons_in_order", "order", "visibility", "created_at", "updated_at" ], "type": "object" }, "CourseStudent": { "description": "An enrollment record for a student in a course, including progress and completion metrics.", "properties": { "completed_lessons_count": { "description": "The total number of lessons this student has marked as completed in the course.", "example": 42, "type": "integer" }, "completion_rate": { "description": "The percentage of available lessons the student has completed, as a value from 0 to 100 rounded to two decimal places.", "example": 6.9, "type": "number" }, "course": { "description": "The course this student is enrolled in.", "properties": { "experience": { "description": "The parent experience that this course belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] } }, "required": [ "id", "title", "experience" ], "type": "object" }, "first_interaction_at": { "description": "The timestamp when the student first interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the course student type.", "type": "string" }, "last_interaction_at": { "description": "The timestamp when the student most recently interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "total_lessons_count": { "description": "The total number of visible lessons available to this student in the course.", "example": 42, "type": "integer" }, "user": { "description": "The user profile of the enrolled student.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed_lessons_count", "completion_rate", "total_lessons_count", "first_interaction_at", "last_interaction_at", "user", "course" ], "type": "object" }, "CourseStudentListItem": { "description": "An enrollment record for a student in a course, including progress and completion metrics.", "properties": { "completed_lessons_count": { "description": "The total number of lessons this student has marked as completed in the course.", "example": 42, "type": "integer" }, "completion_rate": { "description": "The percentage of available lessons the student has completed, as a value from 0 to 100 rounded to two decimal places.", "example": 6.9, "type": "number" }, "first_interaction_at": { "description": "The timestamp when the student first interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the course student type.", "type": "string" }, "last_interaction_at": { "description": "The timestamp when the student most recently interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "total_lessons_count": { "description": "The total number of visible lessons available to this student in the course.", "example": 42, "type": "integer" }, "user": { "description": "The user profile of the enrolled student.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed_lessons_count", "completion_rate", "total_lessons_count", "first_interaction_at", "last_interaction_at", "user" ], "type": "object" }, "CourseVisibilities": { "description": "The available visibilities for a course. Determines how / whether a course is visible to users.", "enum": [ "visible", "hidden" ], "type": "string" }, "CoursesAssessmentQuestionTypes": { "description": "The available types for an assessment question", "enum": [ "short_answer", "true_false", "multiple_choice", "multiple_select" ], "type": "string" }, "CreditTransactionTransfersSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "amount", "created_at" ], "type": "string" }, "Currencies": { "description": "The available currencies on the platform", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "type": "string" }, "CustomCtas": { "description": "The different types of custom CTAs that can be selected.", "enum": [ "get_access", "join", "order_now", "shop_now", "call_now", "donate_now", "contact_us", "sign_up", "subscribe", "purchase", "get_offer", "apply_now", "complete_order" ], "type": "string" }, "CustomFieldTypes": { "const": "text", "description": "The type of the custom field.", "type": "string" }, "Direction": { "description": "The direction of the sort.", "enum": [ "asc", "desc" ], "type": "string" }, "Dispute": { "description": "A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.", "properties": { "access_activity_log": { "description": "A log of IP-based access activity for the customer on Whop, submitted as evidence in the dispute.", "example": "192.168.1.1 - 2024-01-15 12:00:00 UTC", "type": [ "string", "null" ] }, "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "billing_address": { "description": "The customer's billing address from their payment details, submitted as evidence in the dispute.", "example": "123 Main St, New York, NY 10001", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document uploaded as dispute evidence. Null if no cancellation policy has been provided.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "cancellation_policy_disclosure": { "description": "A text disclosure describing the company's cancellation policy, submitted as dispute evidence.", "example": "All sales are final. No refunds after 30 days.", "type": [ "string", "null" ] }, "company": { "description": "The company that the dispute was filed against.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the dispute was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "customer_communication_attachment": { "description": "Evidence of customer communication or product usage, uploaded as a dispute attachment. Null if not provided.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "customer_email_address": { "description": "The customer's email address from their payment details, included in the evidence packet sent to the payment processor. Editable before submission.", "example": "customer@example.com", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's full name from their payment details, included in the evidence packet sent to the payment processor. Editable before submission.", "example": "Jane Doe", "type": [ "string", "null" ] }, "editable": { "description": "Whether the dispute evidence can still be edited and submitted.", "type": [ "boolean", "null" ] }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "needs_response_by": { "description": "The deadline by which dispute evidence must be submitted. Null if no response deadline is set.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "notes": { "description": "Additional freeform notes submitted by the company as part of the dispute evidence.", "example": "Customer used the product for 3 months before disputing.", "type": [ "string", "null" ] }, "payment": { "description": "The original payment that was disputed.", "properties": { "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status" ], "type": [ "object", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "total", "subtotal", "usd_total", "currency", "created_at", "paid_at", "dispute_alerted_at", "payment_method_type", "billing_reason", "card_brand", "card_last4", "user", "member", "membership" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan associated with the disputed payment. Null if the dispute is not linked to a specific plan.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with the disputed payment. Null if the dispute is not linked to a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "product_description": { "description": "A description of the product or service provided, submitted as dispute evidence.", "example": "Monthly subscription to premium analytics dashboard.", "type": [ "string", "null" ] }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document uploaded as dispute evidence. Null if no refund policy has been provided.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "refund_policy_disclosure": { "description": "A text disclosure describing the company's refund policy, submitted as dispute evidence.", "example": "Refunds available within 14 days of purchase.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "An explanation from the company for why a refund was refused, submitted as dispute evidence.", "example": "The customer exceeded the refund window by 60 days.", "type": [ "string", "null" ] }, "service_date": { "description": "The date when the product or service was delivered to the customer, submitted as dispute evidence.", "example": "2024-01-15", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." }, "uncategorized_attachment": { "description": "An additional attachment that does not fit into the standard evidence categories. Null if not provided.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "visa_rdr": { "description": "Whether the dispute was automatically resolved through Visa Rapid Dispute Resolution (RDR).", "type": "boolean" } }, "required": [ "id", "amount", "currency", "status", "editable", "created_at", "visa_rdr", "needs_response_by", "reason", "plan", "product", "company", "payment", "access_activity_log", "billing_address", "cancellation_policy_disclosure", "customer_email_address", "customer_name", "notes", "product_description", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "cancellation_policy_attachment", "customer_communication_attachment", "refund_policy_attachment", "uncategorized_attachment" ], "type": "object" }, "DisputeAlert": { "description": "A dispute alert represents an early warning notification from a payment processor about a potential dispute or chargeback.", "properties": { "alert_type": { "$ref": "#/components/schemas/DisputeAlertTypes", "description": "The type of the dispute alert." }, "amount": { "description": "The alerted amount in the specified currency.", "example": 6.9, "type": "number" }, "charge_for_alert": { "description": "Whether this alert incurs a charge.", "type": "boolean" }, "created_at": { "description": "The time the dispute alert was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the alerted amount." }, "dispute": { "description": "The dispute associated with the dispute alert.", "properties": { "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the dispute was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." } }, "required": [ "id", "amount", "currency", "status", "reason", "created_at" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier of the dispute alert.", "example": "dspa_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with the dispute alert.", "properties": { "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status" ], "type": [ "object", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "total", "subtotal", "usd_total", "currency", "created_at", "paid_at", "dispute_alerted_at", "payment_method_type", "billing_reason", "card_brand", "card_last4", "user", "member", "membership" ], "type": [ "object", "null" ] }, "transaction_date": { "description": "The date of the original transaction.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "alert_type", "amount", "currency", "created_at", "transaction_date", "charge_for_alert", "payment", "dispute" ], "type": "object" }, "DisputeAlertListItem": { "description": "A dispute alert represents an early warning notification from a payment processor about a potential dispute or chargeback.", "properties": { "alert_type": { "$ref": "#/components/schemas/DisputeAlertTypes", "description": "The type of the dispute alert." }, "amount": { "description": "The alerted amount in the specified currency.", "example": 6.9, "type": "number" }, "charge_for_alert": { "description": "Whether this alert incurs a charge.", "type": "boolean" }, "created_at": { "description": "The time the dispute alert was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the alerted amount." }, "dispute": { "description": "The dispute associated with the dispute alert.", "properties": { "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier of the dispute alert.", "example": "dspa_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with the dispute alert.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "transaction_date": { "description": "The date of the original transaction.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "alert_type", "amount", "currency", "created_at", "transaction_date", "charge_for_alert", "payment", "dispute" ], "type": "object" }, "DisputeAlertTypes": { "description": "The type of dispute alert.", "enum": [ "dispute", "dispute_rdr", "fraud" ], "type": "string" }, "DisputeListItem": { "description": "A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.", "properties": { "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "company": { "description": "The company that the dispute was filed against.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the dispute was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "editable": { "description": "Whether the dispute evidence can still be edited and submitted.", "type": [ "boolean", "null" ] }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "needs_response_by": { "description": "The deadline by which dispute evidence must be submitted. Null if no response deadline is set.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment": { "description": "The original payment that was disputed.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan associated with the disputed payment. Null if the dispute is not linked to a specific plan.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with the disputed payment. Null if the dispute is not linked to a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." }, "visa_rdr": { "description": "Whether the dispute was automatically resolved through Visa Rapid Dispute Resolution (RDR).", "type": "boolean" } }, "required": [ "id", "amount", "currency", "status", "editable", "created_at", "visa_rdr", "needs_response_by", "reason", "plan", "product", "company", "payment" ], "type": "object" }, "DisputeStatuses": { "description": "The possible statuses of a dispute", "enum": [ "warning_needs_response", "warning_under_review", "warning_closed", "needs_response", "under_review", "won", "lost", "closed", "other" ], "type": "string" }, "DmChannel": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "created_at": { "description": "The time the entity was created (in milliseconds since Unix epoch)", "example": "123.45", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "name", "last_message_at" ], "type": "object" }, "DmChannelListItem": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "created_at": { "description": "The time the entity was created (in milliseconds since Unix epoch)", "example": "123.45", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "name", "last_message_at" ], "type": "object" }, "DmMember": { "description": "A user's membership record in a messaging channel, including notification preferences and read state.", "properties": { "channel_id": { "description": "The unique identifier of the messaging channel this membership belongs to.", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_viewed_at": { "description": "The timestamp when this member last viewed the channel, as a Unix timestamp in milliseconds. Null if the member has never viewed the channel.", "example": "123.45", "type": [ "string", "null" ] }, "notification_preference": { "$ref": "#/components/schemas/DmsFeedMemberNotificationPreferences", "description": "The notification level for this channel: all, mentions, or none." }, "status": { "$ref": "#/components/schemas/DmsFeedMemberStatuses", "description": "The current state of this membership: requested, accepted, hidden, closed, or archived." }, "user_id": { "description": "The unique identifier of the user who holds this channel membership.", "type": "string" } }, "required": [ "id", "user_id", "channel_id", "status", "last_viewed_at", "notification_preference" ], "type": "object" }, "DmMemberListItem": { "description": "A user's membership record in a messaging channel, including notification preferences and read state.", "properties": { "channel_id": { "description": "The unique identifier of the messaging channel this membership belongs to.", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_viewed_at": { "description": "The timestamp when this member last viewed the channel, as a Unix timestamp in milliseconds. Null if the member has never viewed the channel.", "example": "123.45", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DmsFeedMemberStatuses", "description": "The current state of this membership: requested, accepted, hidden, closed, or archived." }, "user_id": { "description": "The unique identifier of the user who holds this channel membership.", "type": "string" } }, "required": [ "id", "user_id", "channel_id", "status", "last_viewed_at" ], "type": "object" }, "DmsFeedMemberNotificationPreferences": { "description": "The notification preferences for a DMs feed member", "enum": [ "all", "mentions", "none" ], "type": "string" }, "DmsFeedMemberStatuses": { "description": " The statuses of a DMs feed member", "enum": [ "requested", "accepted", "hidden", "closed", "archived" ], "type": "string" }, "DmsPostTypes": { "description": "The types of post", "enum": [ "regular", "system", "automated" ], "type": "string" }, "EmbedTypes": { "description": "The type of embed for a lesson", "enum": [ "youtube", "loom" ], "type": "string" }, "EntriesSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at" ], "type": "string" }, "Entry": { "description": "An entry represents a user's signup for a waitlisted plan.", "properties": { "created_at": { "description": "The datetime the entry was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "custom_field_responses": { "description": "The list of responses collected from the user when submitting their waitlist entry.", "items": { "description": "The response from a custom field on checkout", "properties": { "answer": { "description": "The response a user gave to the specific question or field.", "type": "string" }, "id": { "description": "The unique identifier for the custom field response.", "example": "cfrp_xxxxxxxxxxxxx", "type": "string" }, "question": { "description": "The question asked by the custom field", "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "type": [ "array", "null" ] }, "id": { "description": "The unique identifier for the entry.", "example": "entry_xxxxxxxxxxxx", "type": "string" }, "plan": { "description": "The waitlisted plan that this entry is a signup for.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with this entry's waitlisted plan. Null if the plan is not tied to a product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/EntryStatus", "description": "The current status of the waitlist entry (e.g., drafted, pending, approved, denied)." }, "user": { "description": "The user who submitted this waitlist entry.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "plan", "product", "status", "user", "created_at", "custom_field_responses" ], "type": "object" }, "EntryListItem": { "description": "An entry represents a user's signup for a waitlisted plan.", "properties": { "created_at": { "description": "The datetime the entry was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the entry.", "example": "entry_xxxxxxxxxxxx", "type": "string" }, "plan": { "description": "The waitlisted plan that this entry is a signup for.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with this entry's waitlisted plan. Null if the plan is not tied to a product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/EntryStatus", "description": "The current status of the waitlist entry (e.g., drafted, pending, approved, denied)." }, "user": { "description": "The user who submitted this waitlist entry.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "plan", "product", "status", "user", "created_at" ], "type": "object" }, "EntryStatus": { "description": "The status of an entry to a waitlist.", "enum": [ "drafted", "pending", "approved", "denied", "any" ], "type": "string" }, "EventActionSource": { "description": "The channel where an event originated", "enum": [ "email", "website", "app", "phone_call", "chat", "physical_store", "system_generated", "business_messaging", "other" ], "type": "string" }, "EventGender": { "description": "Gender", "enum": [ "male", "female" ], "type": "string" }, "EventName": { "description": "The type of conversion or engagement event", "enum": [ "lead", "submit_application", "contact", "complete_registration", "schedule", "view_content", "add_to_cart", "custom", "page" ], "type": "string" }, "Experience": { "description": "An experience is a feature or content module within a product, such as a chat, course, or custom app.", "properties": { "app": { "description": "The app that powers this experience, defining its interface and behavior.", "properties": { "icon": { "description": "The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.", "example": "Courses", "type": "string" } }, "required": [ "id", "name", "icon" ], "type": "object" }, "company": { "description": "The company that owns this experience.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the experience was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "The custom logo image for this experience. Null if no custom logo has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "is_public": { "description": "Whether this experience is publicly visible to all users, including those without a membership.", "type": "boolean" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" }, "order": { "description": "The sort position of this experience within its section. Lower values appear first. Null if no position has been set.", "example": "123.45", "type": [ "string", "null" ] }, "products": { "description": "The list of products this experience is attached to, which determines which customers have access. Empty if the experience is only visible to authorized company team members.", "items": { "description": "A product is a digital good or service sold on Whop. Products contain plans for pricing and experiences for content delivery.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug used in the product's public link (e.g., 'my-product' in whop.com/company/my-product).", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "route", "title" ], "type": "object" }, "type": "array" } }, "required": [ "id", "name", "order", "is_public", "created_at", "app", "image", "company", "products" ], "type": "object" }, "ExperienceAccessLevels": { "description": "The different access levels for experiences (PUBLIC IS NEVER USED ANYMORE).", "enum": [ "public", "private" ], "type": "string" }, "ExperienceListItem": { "description": "An experience is a feature or content module within a product, such as a chat, course, or custom app.", "properties": { "app": { "description": "The app that powers this experience, defining its interface and behavior.", "properties": { "icon": { "description": "The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.", "example": "Courses", "type": "string" } }, "required": [ "id", "name", "icon" ], "type": "object" }, "company": { "description": "The company that owns this experience.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the experience was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "The custom logo image for this experience. Null if no custom logo has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "is_public": { "description": "Whether this experience is publicly visible to all users, including those without a membership.", "type": "boolean" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" }, "order": { "description": "The sort position of this experience within its section. Lower values appear first. Null if no position has been set.", "example": "123.45", "type": [ "string", "null" ] } }, "required": [ "id", "name", "order", "is_public", "created_at", "app", "image", "company" ], "type": "object" }, "ExternalAdSortableColumns": { "description": "Columns that the listAds query can sort by. Deprecated — use AdOrder.", "enum": [ "spend", "return_on_ad_spend", "roas" ], "type": "string" }, "ExternalAdStatuses": { "description": "The status of an external ad.", "enum": [ "active", "paused", "inactive", "in_review", "rejected", "flagged" ], "type": "string" }, "FeeMarkup": { "description": "A fee markup configuration that defines additional charges applied to transactions for a platform's connected accounts.", "properties": { "created_at": { "description": "The datetime the fee markup was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "fee_type": { "$ref": "#/components/schemas/FeeMarkupTypes", "description": "The category of fee this markup applies to." }, "fixed_fee_usd": { "description": "A flat fee charged per transaction, in USD. Ranges from 0 to 50. Null if no fixed fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for the fee markup.", "type": "string" }, "notes": { "description": "Internal notes about this fee markup, visible only to administrators. Null if no notes have been added.", "example": "Approved by finance team on 2024-01-15", "type": [ "string", "null" ] }, "percentage_fee": { "description": "A percentage-based fee charged per transaction. Ranges from 0 to 25. Null if no percentage fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the fee markup was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "fee_type", "percentage_fee", "fixed_fee_usd", "notes", "created_at", "updated_at" ], "type": "object" }, "FeeMarkupListItem": { "description": "A fee markup configuration that defines additional charges applied to transactions for a platform's connected accounts.", "properties": { "created_at": { "description": "The datetime the fee markup was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "fee_type": { "$ref": "#/components/schemas/FeeMarkupTypes", "description": "The category of fee this markup applies to." }, "fixed_fee_usd": { "description": "A flat fee charged per transaction, in USD. Ranges from 0 to 50. Null if no fixed fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for the fee markup.", "type": "string" }, "notes": { "description": "Internal notes about this fee markup, visible only to administrators. Null if no notes have been added.", "example": "Approved by finance team on 2024-01-15", "type": [ "string", "null" ] }, "percentage_fee": { "description": "A percentage-based fee charged per transaction. Ranges from 0 to 25. Null if no percentage fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the fee markup was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "fee_type", "percentage_fee", "fixed_fee_usd", "notes", "created_at", "updated_at" ], "type": "object" }, "FeeMarkupTypes": { "description": "The types of fee markups that can be configured", "enum": [ "crypto_withdrawal_markup", "rtp_withdrawal_markup", "next_day_bank_withdrawal_markup", "bank_wire_withdrawal_markup", "digital_wallet_withdrawal_markup" ], "type": "string" }, "File": { "description": "A file that has been uploaded or is pending upload.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded file, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the file.", "example": "file_xxxxxxxxxxxxx", "type": "string" }, "size": { "description": "The file size in bytes. Null if the file has not finished uploading.", "example": "123.45", "type": [ "string", "null" ] }, "upload_status": { "$ref": "#/components/schemas/UploadStatuses", "description": "The current upload status of the file (e.g., pending, ready)." }, "url": { "description": "The URL for accessing the file. For public files, this is a permanent CDN URL. For private files, this is a signed URL that expires. Null if the file has not finished uploading.", "type": [ "string", "null" ] }, "visibility": { "$ref": "#/components/schemas/FileVisibility", "description": "Whether the file is publicly accessible or requires authentication." } }, "required": [ "id", "upload_status", "filename", "content_type", "size", "url", "visibility" ], "type": "object" }, "FileVisibility": { "description": "Controls whether an uploaded file is publicly accessible or requires authentication to access.", "enum": [ "public", "private" ], "type": "string" }, "Forum": { "description": "A discussion forum where members can create posts, comment, and react, belonging to an experience.", "properties": { "email_notification_preference": { "$ref": "#/components/schemas/ForumEmailNotificationPreferences", "description": "The email notification setting that controls which posts trigger email alerts. One of: all_admin_posts, only_weekly_summary, none." }, "experience": { "description": "The parent experience that this forum belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "who_can_comment": { "$ref": "#/components/schemas/ForumWhoCanCommentTypes", "description": "The permission level controlling who can comment on posts. One of: everyone, admins." }, "who_can_post": { "$ref": "#/components/schemas/ForumWhoCanPostTypes", "description": "The permission level controlling who can create new posts. One of: everyone, admins." } }, "required": [ "id", "experience", "who_can_post", "who_can_comment", "email_notification_preference" ], "type": "object" }, "ForumEmailNotificationPreferences": { "description": "Email notification preference option for a forum feed", "enum": [ "all_admin_posts", "only_weekly_summary", "none" ], "type": "string" }, "ForumListItem": { "description": "A discussion forum where members can create posts, comment, and react, belonging to an experience.", "properties": { "email_notification_preference": { "$ref": "#/components/schemas/ForumEmailNotificationPreferences", "description": "The email notification setting that controls which posts trigger email alerts. One of: all_admin_posts, only_weekly_summary, none." }, "experience": { "description": "The parent experience that this forum belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "who_can_comment": { "$ref": "#/components/schemas/ForumWhoCanCommentTypes", "description": "The permission level controlling who can comment on posts. One of: everyone, admins." }, "who_can_post": { "$ref": "#/components/schemas/ForumWhoCanPostTypes", "description": "The permission level controlling who can create new posts. One of: everyone, admins." } }, "required": [ "id", "experience", "who_can_post", "who_can_comment", "email_notification_preference" ], "type": "object" }, "ForumPost": { "description": "A post or comment in a forum feed, supporting rich text, attachments, polls, and reactions.", "properties": { "attachments": { "description": "All file attachments on this post, such as images, documents, and videos.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "comment_count": { "description": "The total number of direct comments on this post.", "example": 42, "type": "integer" }, "content": { "description": "The body of the forum post in Markdown format. Null if the post is paywalled and the current user does not have access.", "example": "## My Strategy\n\nHere are the key steps...", "type": [ "string", "null" ] }, "created_at": { "description": "The time this post was created, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether this post has been edited after its initial creation.", "type": "boolean" }, "is_pinned": { "description": "Whether this post is pinned to the top of the forum feed.", "type": "boolean" }, "is_poster_admin": { "description": "Whether the author of this post is an admin of the company that owns the forum.", "type": "boolean" }, "like_count": { "description": "The total number of like reactions this post has received.", "example": 42, "type": [ "integer", "null" ] }, "parent_id": { "description": "The unique identifier of the parent post. Null if this is a top-level post.", "type": [ "string", "null" ] }, "title": { "description": "The headline of the forum post. Null if the post has no title.", "example": "Weekly Market Analysis - February 2025", "type": [ "string", "null" ] }, "updated_at": { "description": "The time this post was last updated, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this forum post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The total number of times this post has been viewed by users.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "title", "content", "created_at", "updated_at", "is_edited", "is_poster_admin", "is_pinned", "parent_id", "user", "attachments", "view_count", "like_count", "comment_count" ], "type": "object" }, "ForumPostListItem": { "description": "A post or comment in a forum feed, supporting rich text, attachments, polls, and reactions.", "properties": { "attachments": { "description": "All file attachments on this post, such as images, documents, and videos.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "comment_count": { "description": "The total number of direct comments on this post.", "example": 42, "type": "integer" }, "content": { "description": "The body of the forum post in Markdown format. Null if the post is paywalled and the current user does not have access.", "example": "## My Strategy\n\nHere are the key steps...", "type": [ "string", "null" ] }, "created_at": { "description": "The time this post was created, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether this post has been edited after its initial creation.", "type": "boolean" }, "is_pinned": { "description": "Whether this post is pinned to the top of the forum feed.", "type": "boolean" }, "is_poster_admin": { "description": "Whether the author of this post is an admin of the company that owns the forum.", "type": "boolean" }, "like_count": { "description": "The total number of like reactions this post has received.", "example": 42, "type": [ "integer", "null" ] }, "parent_id": { "description": "The unique identifier of the parent post. Null if this is a top-level post.", "type": [ "string", "null" ] }, "title": { "description": "The headline of the forum post. Null if the post has no title.", "example": "Weekly Market Analysis - February 2025", "type": [ "string", "null" ] }, "updated_at": { "description": "The time this post was last updated, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this forum post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The total number of times this post has been viewed by users.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "title", "content", "created_at", "updated_at", "is_edited", "is_poster_admin", "is_pinned", "parent_id", "user", "attachments", "view_count", "like_count", "comment_count" ], "type": "object" }, "ForumPostVisibilityTypes": { "description": "The visibility types for forum posts", "enum": [ "members_only", "globally_visible" ], "type": "string" }, "ForumWhoCanCommentTypes": { "description": "Who can comment on a forum feed", "enum": [ "everyone", "admins" ], "type": "string" }, "ForumWhoCanPostTypes": { "description": "Who can post on a forum feed", "enum": [ "everyone", "admins" ], "type": "string" }, "FriendlyReceiptStatus": { "description": "The friendly status of a payment. This is a derived status that provides a human-readable summary of the payment state, combining the underlying status and substatus fields.", "enum": [ "succeeded", "pending", "failed", "past_due", "canceled", "price_too_low", "uncollectible", "refunded", "auto_refunded", "partially_refunded", "dispute_warning", "dispute_needs_response", "dispute_warning_needs_response", "resolution_needs_response", "dispute_under_review", "dispute_warning_under_review", "resolution_under_review", "dispute_won", "dispute_warning_closed", "resolution_won", "dispute_lost", "dispute_closed", "resolution_lost", "drafted", "incomplete", "unresolved", "open_dispute", "open_resolution" ], "type": "string" }, "GlobalAffiliateStatuses": { "description": "The different statuses of the global affiliate program for a product.", "enum": [ "enabled", "disabled" ], "type": "string" }, "Granularities": { "description": "Bucket size for external ad stat rows.", "enum": [ "hourly", "daily", "weekly", "monthly" ], "type": "string" }, "IdentityProfile": { "description": "A consolidated identity or business profile synced from verification provider data.", "properties": { "business_address": { "description": "Registered business address reported by the identity provider. Present on `business` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "Business entity name. Present on `business` profiles.", "type": [ "string", "null" ] }, "business_structure": { "description": "Reported legal structure of a business profile (e.g. `corp`, `llc`). Provider-specific values; present on `business` profiles.", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-3 country code (e.g. `USA`, `GBR`). For individuals this is the country of citizenship or residence reported by the identity provider; for businesses this is the country of incorporation.", "type": [ "string", "null" ] }, "created_at": { "description": "When the identity profile was first created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "date_of_birth": { "description": "ISO date (`YYYY-MM-DD`) reported by the identity provider. Present on `individual` profiles.", "type": [ "string", "null" ] }, "email": { "description": "Email address reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "first_name": { "description": "Individual's first name.", "type": [ "string", "null" ] }, "id": { "description": "The tag of the identity profile (idpf_xxx).", "example": "idpf_xxxxxxxxxxxxx", "type": "string" }, "last_name": { "description": "Individual's last name.", "type": [ "string", "null" ] }, "linked_companies": { "description": "The companies this identity profile is currently linked to. Only populated for direct Whop user sessions; always empty when authenticated via API key, app, or OAuth scope (a single identity can be linked to companies the calling platform is not entitled to see).", "items": { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": "array" }, "personal_address": { "description": "Residential address reported by the identity provider. Present on `individual` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "phone": { "description": "Phone number reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "profile_type": { "description": "Whether this is an 'individual' or 'business' profile.", "type": "string" }, "status": { "$ref": "#/components/schemas/IdentityProfileStatuses", "description": "Derived verification status across all linked verifications." }, "updated_at": { "description": "When the identity profile was last synced from a verification.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verifications": { "description": "All verification attempts attached to this identity profile, ordered most-recent first.", "items": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "created_at": { "description": "When the verification record was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "session_url": { "description": "A URL the user can visit to complete the verification process. Null if the session does not require user interaction.", "example": "https://verify.stripe.com/session/abc123", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "session_url", "last_error_code", "last_error_reason", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "id", "profile_type", "status", "first_name", "last_name", "date_of_birth", "email", "phone", "personal_address", "business_name", "business_structure", "business_address", "country", "linked_companies", "verifications", "created_at", "updated_at" ], "type": "object" }, "IdentityProfileKinds": { "description": "The kind of identity profile (individual vs business).", "enum": [ "individual", "business" ], "type": "string" }, "IdentityProfileListItem": { "description": "A consolidated identity or business profile synced from verification provider data.", "properties": { "business_address": { "description": "Registered business address reported by the identity provider. Present on `business` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "Business entity name. Present on `business` profiles.", "type": [ "string", "null" ] }, "business_structure": { "description": "Reported legal structure of a business profile (e.g. `corp`, `llc`). Provider-specific values; present on `business` profiles.", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-3 country code (e.g. `USA`, `GBR`). For individuals this is the country of citizenship or residence reported by the identity provider; for businesses this is the country of incorporation.", "type": [ "string", "null" ] }, "created_at": { "description": "When the identity profile was first created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "date_of_birth": { "description": "ISO date (`YYYY-MM-DD`) reported by the identity provider. Present on `individual` profiles.", "type": [ "string", "null" ] }, "email": { "description": "Email address reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "first_name": { "description": "Individual's first name.", "type": [ "string", "null" ] }, "id": { "description": "The tag of the identity profile (idpf_xxx).", "example": "idpf_xxxxxxxxxxxxx", "type": "string" }, "last_name": { "description": "Individual's last name.", "type": [ "string", "null" ] }, "linked_companies": { "description": "The companies this identity profile is currently linked to. Only populated for direct Whop user sessions; always empty when authenticated via API key, app, or OAuth scope (a single identity can be linked to companies the calling platform is not entitled to see).", "items": { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": "array" }, "personal_address": { "description": "Residential address reported by the identity provider. Present on `individual` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "phone": { "description": "Phone number reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "profile_type": { "description": "Whether this is an 'individual' or 'business' profile.", "type": "string" }, "status": { "$ref": "#/components/schemas/IdentityProfileStatuses", "description": "Derived verification status across all linked verifications." }, "updated_at": { "description": "When the identity profile was last synced from a verification.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verifications": { "description": "All verification attempts attached to this identity profile, ordered most-recent first.", "items": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "created_at": { "description": "When the verification record was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "session_url": { "description": "A URL the user can visit to complete the verification process. Null if the session does not require user interaction.", "example": "https://verify.stripe.com/session/abc123", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "session_url", "last_error_code", "last_error_reason", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "id", "profile_type", "status", "first_name", "last_name", "date_of_birth", "email", "phone", "personal_address", "business_name", "business_structure", "business_address", "country", "linked_companies", "verifications", "created_at", "updated_at" ], "type": "object" }, "IdentityProfileStatuses": { "description": "Derived verification status for an identity profile.", "enum": [ "not_started", "pending", "approved", "rejected" ], "type": "string" }, "Invoice": { "description": "An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.", "properties": { "created_at": { "description": "The datetime the invoice was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "current_plan": { "description": "The plan that this invoice charges for.", "properties": { "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "formatted_price": { "description": "The formatted price (including currency) for the plan.", "example": "$10.00", "type": "string" }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "formatted_price", "currency" ], "type": "object" }, "due_date": { "description": "The deadline by which payment is expected. Null if the invoice is collected automatically.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer this invoice is addressed to. Null if no email is on file.", "example": "customer@example.com", "type": [ "string", "null" ] }, "fetch_invoice_token": { "description": "A signed token that allows fetching invoice data publicly without authentication.", "example": "eyJhbGciOiJIUzI1NiJ9...", "type": "string" }, "id": { "description": "The unique identifier for the invoice.", "example": "inv_xxxxxxxxxxxxxx", "type": "string" }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatuses", "description": "The current payment status of the invoice, such as draft, open, paid, or void." }, "user": { "description": "The user this invoice is addressed to. Null if the user account has been removed.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "status", "number", "due_date", "email_address", "fetch_invoice_token", "current_plan", "user" ], "type": "object" }, "InvoiceCollectionMethods": { "description": "The method of collection for an invoice.", "enum": [ "send_invoice", "charge_automatically" ], "type": "string" }, "InvoiceListItem": { "description": "An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.", "properties": { "created_at": { "description": "The datetime the invoice was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "current_plan": { "description": "The plan that this invoice charges for.", "properties": { "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "formatted_price": { "description": "The formatted price (including currency) for the plan.", "example": "$10.00", "type": "string" }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "formatted_price", "currency" ], "type": "object" }, "due_date": { "description": "The deadline by which payment is expected. Null if the invoice is collected automatically.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer this invoice is addressed to. Null if no email is on file.", "example": "customer@example.com", "type": [ "string", "null" ] }, "fetch_invoice_token": { "description": "A signed token that allows fetching invoice data publicly without authentication.", "example": "eyJhbGciOiJIUzI1NiJ9...", "type": "string" }, "id": { "description": "The unique identifier for the invoice.", "example": "inv_xxxxxxxxxxxxxx", "type": "string" }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatuses", "description": "The current payment status of the invoice, such as draft, open, paid, or void." }, "user": { "description": "The user this invoice is addressed to. Null if the user account has been removed.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "status", "number", "due_date", "email_address", "fetch_invoice_token", "current_plan", "user" ], "type": "object" }, "InvoiceStatuses": { "description": "The different statuses an invoice can be in", "enum": [ "draft", "open", "paid", "past_due", "uncollectible", "void" ], "type": "string" }, "InvoicesSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at", "due_date" ], "type": "string" }, "Languages": { "description": "The available languages for a course", "enum": [ "en", "es", "it", "pt", "de", "fr", "pl", "ru", "nl", "ca", "tr", "sv", "uk", "no", "fi", "sk", "el", "cs", "hr", "da", "ro", "bg" ], "type": "string" }, "Lead": { "description": "A prospective customer who has expressed interest in a company or product but has not yet purchased.", "properties": { "created_at": { "description": "The datetime the lead was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lead.", "example": "lead_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member record if this lead has converted into a paying customer. Null if the lead has not converted.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this lead. Null if no metadata was provided.", "type": [ "object", "null" ] }, "product": { "description": "The product the lead expressed interest in. Null if the lead is not associated with a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "referrer": { "description": "The URL of the page that referred this lead to the company. Null if no referrer was captured.", "example": "https://twitter.com/whabormarket", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the lead was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user account associated with this lead.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": "object" } }, "required": [ "id", "created_at", "updated_at", "referrer", "metadata", "user", "product", "member" ], "type": "object" }, "LeadListItem": { "description": "A prospective customer who has expressed interest in a company or product but has not yet purchased.", "properties": { "created_at": { "description": "The datetime the lead was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lead.", "example": "lead_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member record if this lead has converted into a paying customer. Null if the lead has not converted.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this lead. Null if no metadata was provided.", "type": [ "object", "null" ] }, "product": { "description": "The product the lead expressed interest in. Null if the lead is not associated with a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "referrer": { "description": "The URL of the page that referred this lead to the company. Null if no referrer was captured.", "example": "https://twitter.com/whabormarket", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the lead was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user account associated with this lead.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": "object" } }, "required": [ "id", "created_at", "updated_at", "referrer", "metadata", "user", "product", "member" ], "type": "object" }, "LedgerAccount": { "description": "A ledger account represents a financial account on Whop that can hold many balances.", "properties": { "balances": { "description": "The balances associated with the account.", "items": { "description": "A cached balance for a LedgerAccount in respect to a currency.", "properties": { "balance": { "description": "The amount of the balance.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the balance." }, "pending_balance": { "description": "The amount of the balance that is pending.", "example": 6.9, "type": "number" }, "reserve_balance": { "description": "The amount of the balance that is reserved.", "example": 6.9, "type": "number" } }, "required": [ "balance", "currency", "pending_balance", "reserve_balance" ], "type": "object" }, "type": "array" }, "id": { "description": "The unique identifier for the ledger account.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" }, "ledger_type": { "$ref": "#/components/schemas/LedgerTypes", "description": "The type of ledger account." }, "owner": { "description": "The owner of the ledger account.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A user account on Whop. Contains profile information, identity details, and social connections.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "typename": { "const": "User", "description": "The typename of this object", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "typename", "id", "name", "username" ], "title": "User", "type": [ "object", "null" ] }, { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" }, "typename": { "const": "Company", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "route", "title" ], "title": "Company", "type": [ "object", "null" ] } ], "type": "object" }, "payments_approval_status": { "description": "The status of payments approval for the ledger account.", "oneOf": [ { "$ref": "#/components/schemas/PaymentsApprovalStatuses" }, { "type": "null" } ] }, "payout_account_details": { "description": "The payout account associated with the LedgerAccount, if any.", "properties": { "address": { "description": "The physical address associated with this payout account", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "state", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "The company's legal name", "type": [ "string", "null" ] }, "business_representative": { "description": "The business representative for this payout account", "properties": { "date_of_birth": { "description": "The date of birth of the business representative in ISO 8601 format (YYYY-MM-DD).", "type": [ "string", "null" ] }, "first_name": { "description": "The first name of the business representative.", "type": [ "string", "null" ] }, "last_name": { "description": "The last name of the business representative.", "type": [ "string", "null" ] }, "middle_name": { "description": "The middle name of the business representative.", "type": [ "string", "null" ] } }, "required": [ "date_of_birth", "first_name", "middle_name", "last_name" ], "type": [ "object", "null" ] }, "email": { "description": "The email address of the representative", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payout account.", "example": "poact_xxxxxxxxxxxx", "type": "string" }, "latest_verification": { "description": "The latest verification for the connected account.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": [ "object", "null" ] }, "phone": { "description": "The business representative's phone", "type": [ "string", "null" ] }, "status": { "description": "The granular calculated status of the payout account reflecting its current KYC and withdrawal readiness state.", "oneOf": [ { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses" }, { "type": "null" } ] } }, "required": [ "id", "status", "business_name", "phone", "email", "business_representative", "address", "latest_verification" ], "type": [ "object", "null" ] }, "transfer_fee": { "description": "The fee for transfers, if applicable.", "example": 6.9, "type": [ "number", "null" ] }, "treasury_balance": { "description": "The balance cache associated with the account by currency.", "properties": { "balance": { "description": "The amount of the balance.", "example": 6.9, "type": "number" }, "balance_usd": { "description": "The balance converted to USD.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the balance." }, "pending_balance": { "description": "The amount of the balance that is pending.", "example": 6.9, "type": "number" }, "reserve_balance": { "description": "The amount of the balance that is reserved.", "example": 6.9, "type": "number" }, "total_withdrawable_balance": { "description": "The amount of the balance that is withdrawable.", "example": 6.9, "type": "number" } }, "required": [ "balance", "balance_usd", "currency", "pending_balance", "reserve_balance", "total_withdrawable_balance" ], "type": [ "object", "null" ] } }, "required": [ "id", "balances", "treasury_balance", "transfer_fee", "payout_account_details", "payments_approval_status", "ledger_type", "owner" ], "type": "object" }, "LedgerTypes": { "description": "The types of ledgers that can be created.", "enum": [ "primary", "pool" ], "type": "string" }, "LessonTypes": { "description": "The available types for a lesson", "enum": [ "text", "video", "pdf", "multi", "quiz", "knowledge_check" ], "type": "string" }, "LessonVisibilities": { "description": "The available visibilities for a lesson. Determines how / whether a lesson is visible to users.", "enum": [ "visible", "hidden" ], "type": "string" }, "Member": { "description": "A member represents a user's relationship with a company on Whop, including their access level, status, and spending history.", "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel", "description": "The access level of the product member. If its admin, the member is an authorized user of the company. If its customer, the member has a valid membership to any product on the company. If its no_access, the member does not have access to the product." }, "company": { "description": "The company for the member.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "company_token_balance": { "description": "The member's token balance for this company. Computed live from the ledger, not from a cache.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the company member was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the company member.", "type": "string" }, "joined_at": { "description": "When the member joined the company", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "most_recent_action": { "description": "The most recent action the member has taken.", "oneOf": [ { "$ref": "#/components/schemas/MemberMostRecentActions" }, { "type": "null" } ] }, "most_recent_action_at": { "description": "The time for the most recent action, if applicable.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MemberStatuses", "description": "The status of the member" }, "updated_at": { "description": "The datetime the company member was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total_spent": { "description": "How much money this customer has spent on the company's products and plans", "example": 6.9, "type": "number" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "joined_at", "access_level", "status", "most_recent_action", "most_recent_action_at", "user", "phone", "usd_total_spent", "company_token_balance", "company" ], "type": "object" }, "MemberListItem": { "description": "A member represents a user's relationship with a company on Whop, including their access level, status, and spending history.", "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel", "description": "The access level of the product member. If its admin, the member is an authorized user of the company. If its customer, the member has a valid membership to any product on the company. If its no_access, the member does not have access to the product." }, "company_token_balance": { "description": "The member's token balance for this company. Computed live from the ledger, not from a cache.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the company member was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the company member.", "type": "string" }, "joined_at": { "description": "When the member joined the company", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "most_recent_action": { "description": "The most recent action the member has taken.", "oneOf": [ { "$ref": "#/components/schemas/MemberMostRecentActions" }, { "type": "null" } ] }, "most_recent_action_at": { "description": "The time for the most recent action, if applicable.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MemberStatuses", "description": "The status of the member" }, "updated_at": { "description": "The datetime the company member was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total_spent": { "description": "How much money this customer has spent on the company's products and plans", "example": 6.9, "type": "number" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "joined_at", "access_level", "status", "most_recent_action", "most_recent_action_at", "user", "phone", "usd_total_spent", "company_token_balance" ], "type": "object" }, "MemberMostRecentActions": { "description": "The different most recent actions a member can have.", "enum": [ "canceling", "churned", "finished_split_pay", "paused", "paid_subscriber", "paid_once", "expiring", "joined", "drafted", "left", "trialing", "pending_entry", "renewing", "past_due" ], "type": "string" }, "MemberStatuses": { "description": "The different statuses a Member can have.", "enum": [ "drafted", "joined", "left" ], "type": "string" }, "MembersSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "usd_total_spent", "created_at", "joined_at", "most_recent_action" ], "type": "string" }, "Membership": { "description": "A membership represents an active relationship between a user and a product. It tracks the user's access, billing status, and renewal schedule.", "properties": { "cancel_at_period_end": { "description": "Whether this membership is set to cancel at the end of the current billing cycle. Only applies to memberships with a recurring plan.", "type": "boolean" }, "cancel_option": { "description": "The category selected for why the member canceled (e.g. too_expensive, switching, missing_features).", "oneOf": [ { "$ref": "#/components/schemas/CancelOptions" }, { "type": "null" } ] }, "canceled_at": { "description": "The time the customer initiated cancellation of this membership. As a Unix timestamp. Null if the membership has not been canceled.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "cancellation_reason": { "description": "Free-text explanation provided by the customer when canceling. Null if the customer did not provide a reason.", "example": "I found a better alternative.", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this membership, if any. Use this to map memberships back to the checkout configuration that created them.", "type": [ "string", "null" ] }, "company": { "description": "The company this membership belongs to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the membership was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this membership's billing. Null if the membership is free.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "custom_field_responses": { "description": "The customer's responses to custom checkout questions configured on the product at the time of purchase.", "items": { "description": "The response from a custom field on checkout", "properties": { "answer": { "description": "The response a user gave to the specific question or field.", "type": "string" }, "id": { "description": "The unique identifier for the custom field response.", "example": "cfrp_xxxxxxxxxxxxx", "type": "string" }, "question": { "description": "The question asked by the custom field", "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "type": "array" }, "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "The time the user first joined the company associated with this membership. As a Unix timestamp. Null if the member record does not exist.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "license_key": { "description": "The software license key associated with this membership. Only present if the product includes a Whop Software Licensing experience. Null otherwise.", "example": "A1B2C3-D4E5F6-G7H8I9", "type": [ "string", "null" ] }, "manage_url": { "description": "The URL where the customer can view and manage this membership, including cancellation and plan changes. Null if no member record exists.", "example": "https://whop.com/billing/manage/mem_abc123", "type": [ "string", "null" ] }, "member": { "description": "The member record linking the user to the company for this membership. Null if the member record has not been created yet.", "properties": { "id": { "description": "The unique identifier for the member.", "example": "mber_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs for the membership (commonly used for software licensing, e.g., HWID). Max 50 keys, 500 chars per key, 5000 chars per value.", "type": [ "object", "null" ] }, "payment_collection_paused": { "description": "Whether recurring payment collection for this membership is temporarily paused by the company.", "type": "boolean" }, "plan": { "description": "The plan the customer purchased to create this membership.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": "object" }, "product": { "description": "The product this membership grants access to.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "metadata" ], "type": "object" }, "promo_code": { "description": "The promotional code currently applied to this membership's billing. Null if no promo code is active.", "properties": { "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "renewal_period_end": { "description": "The end of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "renewal_period_start": { "description": "The start of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The current lifecycle status of the membership (e.g., active, trialing, past_due, canceled, expired, completed)." }, "updated_at": { "description": "The datetime the membership was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this membership. Null if the user account has been deleted.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "status", "created_at", "joined_at", "updated_at", "manage_url", "member", "user", "renewal_period_start", "renewal_period_end", "cancel_at_period_end", "cancel_option", "cancellation_reason", "canceled_at", "currency", "company", "plan", "promo_code", "product", "license_key", "metadata", "payment_collection_paused", "checkout_configuration_id", "custom_field_responses" ], "type": "object" }, "MembershipCancellationModes": { "description": "The mode of cancellation for a membership", "enum": [ "at_period_end", "immediate" ], "type": "string" }, "MembershipListItem": { "description": "A membership represents an active relationship between a user and a product. It tracks the user's access, billing status, and renewal schedule.", "properties": { "cancel_at_period_end": { "description": "Whether this membership is set to cancel at the end of the current billing cycle. Only applies to memberships with a recurring plan.", "type": "boolean" }, "cancel_option": { "description": "The category selected for why the member canceled (e.g. too_expensive, switching, missing_features).", "oneOf": [ { "$ref": "#/components/schemas/CancelOptions" }, { "type": "null" } ] }, "canceled_at": { "description": "The time the customer initiated cancellation of this membership. As a Unix timestamp. Null if the membership has not been canceled.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "cancellation_reason": { "description": "Free-text explanation provided by the customer when canceling. Null if the customer did not provide a reason.", "example": "I found a better alternative.", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this membership, if any. Use this to map memberships back to the checkout configuration that created them.", "type": [ "string", "null" ] }, "company": { "description": "The company this membership belongs to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the membership was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this membership's billing. Null if the membership is free.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "The time the user first joined the company associated with this membership. As a Unix timestamp. Null if the member record does not exist.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "license_key": { "description": "The software license key associated with this membership. Only present if the product includes a Whop Software Licensing experience. Null otherwise.", "example": "A1B2C3-D4E5F6-G7H8I9", "type": [ "string", "null" ] }, "manage_url": { "description": "The URL where the customer can view and manage this membership, including cancellation and plan changes. Null if no member record exists.", "example": "https://whop.com/billing/manage/mem_abc123", "type": [ "string", "null" ] }, "member": { "description": "The member record linking the user to the company for this membership. Null if the member record has not been created yet.", "properties": { "id": { "description": "The unique identifier for the member.", "example": "mber_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs for the membership (commonly used for software licensing, e.g., HWID). Max 50 keys, 500 chars per key, 5000 chars per value.", "type": [ "object", "null" ] }, "payment_collection_paused": { "description": "Whether recurring payment collection for this membership is temporarily paused by the company.", "type": "boolean" }, "plan": { "description": "The plan the customer purchased to create this membership.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": "object" }, "product": { "description": "The product this membership grants access to.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "metadata" ], "type": "object" }, "promo_code": { "description": "The promotional code currently applied to this membership's billing. Null if no promo code is active.", "properties": { "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "renewal_period_end": { "description": "The end of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "renewal_period_start": { "description": "The start of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The current lifecycle status of the membership (e.g., active, trialing, past_due, canceled, expired, completed)." }, "updated_at": { "description": "The datetime the membership was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this membership. Null if the user account has been deleted.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "status", "created_at", "joined_at", "updated_at", "manage_url", "member", "user", "renewal_period_start", "renewal_period_end", "cancel_at_period_end", "cancel_option", "cancellation_reason", "canceled_at", "currency", "company", "plan", "promo_code", "product", "license_key", "metadata", "payment_collection_paused", "checkout_configuration_id" ], "type": "object" }, "MembershipStatus": { "description": "The status of a membership", "enum": [ "trialing", "active", "past_due", "completed", "canceled", "expired", "unresolved", "drafted", "canceling" ], "type": "string" }, "MembershipsSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at", "status", "canceled_at", "date_joined", "total_spend" ], "type": "string" }, "Message": { "description": "A message sent within an experience chat, direct message, or group chat.", "properties": { "content": { "description": "The message content formatted as Markdown. Null if the message has no text content.", "example": "Hey, are you available for a **quick call**?", "type": [ "string", "null" ] }, "created_at": { "description": "The timestamp when this message was originally created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether the message content has been edited after it was originally sent.", "type": "boolean" }, "is_pinned": { "description": "Whether this message is pinned to the top of the channel for easy access.", "type": "boolean" }, "mentions": { "description": "A list of user IDs that are explicitly mentioned in this message.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" }, "mentions_everyone": { "description": "Whether the message includes an @everyone mention that notifies all channel members.", "type": "boolean" }, "message_type": { "$ref": "#/components/schemas/DmsPostTypes", "description": "The classification of this message: regular, system, or automated." }, "poll": { "description": "A poll attached to this message. Null if the message does not contain a poll.", "properties": { "options": { "description": "The options for the poll", "items": { "description": "Represents a single poll option", "properties": { "id": { "description": "The unique identifier for the poll option.", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "options" ], "type": [ "object", "null" ] }, "poll_votes": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "option_id": { "description": "The reaction that was used", "type": [ "string", "null" ] } }, "required": [ "option_id", "count" ], "type": "object" }, "type": "array" }, "reaction_counts": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "emoji": { "description": "The emoji that was used in shortcode format (:heart:)", "type": [ "string", "null" ] } }, "required": [ "emoji", "count" ], "type": "object" }, "type": "array" }, "replying_to_message_id": { "description": "The unique identifier of the message this post is replying to. Null if this is not a reply.", "type": [ "string", "null" ] }, "updated_at": { "description": "The timestamp when this message was last modified.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this message.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The number of unique views this message has received. Null if view tracking is not enabled for this channel.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "content", "created_at", "updated_at", "poll", "replying_to_message_id", "is_edited", "is_pinned", "message_type", "mentions", "mentions_everyone", "user", "view_count", "reaction_counts", "poll_votes" ], "type": "object" }, "MessageChannelOrder": { "description": "Sort options for message channels", "enum": [ "created_at", "last_post_sent_at" ], "type": "string" }, "MessageListItem": { "description": "A message sent within an experience chat, direct message, or group chat.", "properties": { "content": { "description": "The message content formatted as Markdown. Null if the message has no text content.", "example": "Hey, are you available for a **quick call**?", "type": [ "string", "null" ] }, "created_at": { "description": "The timestamp when this message was originally created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether the message content has been edited after it was originally sent.", "type": "boolean" }, "is_pinned": { "description": "Whether this message is pinned to the top of the channel for easy access.", "type": "boolean" }, "mentions": { "description": "A list of user IDs that are explicitly mentioned in this message.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" }, "mentions_everyone": { "description": "Whether the message includes an @everyone mention that notifies all channel members.", "type": "boolean" }, "message_type": { "$ref": "#/components/schemas/DmsPostTypes", "description": "The classification of this message: regular, system, or automated." }, "poll": { "description": "A poll attached to this message. Null if the message does not contain a poll.", "properties": { "options": { "description": "The options for the poll", "items": { "description": "Represents a single poll option", "properties": { "id": { "description": "The unique identifier for the poll option.", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "options" ], "type": [ "object", "null" ] }, "poll_votes": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "option_id": { "description": "The reaction that was used", "type": [ "string", "null" ] } }, "required": [ "option_id", "count" ], "type": "object" }, "type": "array" }, "reaction_counts": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "emoji": { "description": "The emoji that was used in shortcode format (:heart:)", "type": [ "string", "null" ] } }, "required": [ "emoji", "count" ], "type": "object" }, "type": "array" }, "replying_to_message_id": { "description": "The unique identifier of the message this post is replying to. Null if this is not a reply.", "type": [ "string", "null" ] }, "updated_at": { "description": "The timestamp when this message was last modified.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this message.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The number of unique views this message has received. Null if view tracking is not enabled for this channel.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "content", "created_at", "updated_at", "poll", "replying_to_message_id", "is_edited", "is_pinned", "message_type", "mentions", "mentions_everyone", "user", "view_count", "reaction_counts", "poll_votes" ], "type": "object" }, "MetaAdGroupPlatformConfigBidStrategy": { "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP", "COST_CAP", "LOWEST_COST_WITH_MIN_ROAS" ], "type": "string" }, "MetaAdGroupPlatformConfigBillingEvent": { "enum": [ "APP_INSTALLS", "CLICKS", "IMPRESSIONS", "LINK_CLICKS", "NONE", "OFFER_CLAIMS", "PAGE_LIKES", "POST_ENGAGEMENT", "THRUPLAY", "PURCHASE", "LISTING_INTERACTION" ], "type": "string" }, "MetaAdGroupPlatformConfigDestinationType": { "enum": [ "UNDEFINED", "WEBSITE", "APP", "FACEBOOK", "MESSENGER", "WHATSAPP", "INSTAGRAM_DIRECT", "INSTAGRAM_PROFILE", "PHONE_CALL", "SHOP_AUTOMATIC", "APPLINKS_AUTOMATIC", "ON_AD", "ON_POST", "ON_VIDEO", "ON_PAGE", "ON_EVENT", "MESSAGING_MESSENGER_WHATSAPP", "MESSAGING_INSTAGRAM_DIRECT_MESSENGER", "MESSAGING_INSTAGRAM_DIRECT_WHATSAPP", "MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP", "INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE", "FACEBOOK_PAGE", "INSTAGRAM_LIVE", "FACEBOOK_LIVE", "IMAGINE", "LEAD_FROM_IG_DIRECT", "LEAD_FROM_MESSENGER", "LEAD_FORM_MESSENGER", "WEBSITE_AND_LEAD_FORM", "WEBSITE_AND_PHONE_CALL", "BROADCAST_CHANNEL" ], "type": "string" }, "MetaAdGroupPlatformConfigLeadConversionLocation": { "enum": [ "website", "instant_forms", "website_and_instant_forms", "messenger", "instagram", "calls", "app" ], "type": "string" }, "MetaAdGroupPlatformConfigOptimizationGoal": { "enum": [ "NONE", "APP_INSTALLS", "AD_RECALL_LIFT", "ENGAGED_USERS", "EVENT_RESPONSES", "IMPRESSIONS", "LEAD_GENERATION", "QUALITY_LEAD", "LINK_CLICKS", "OFFSITE_CONVERSIONS", "PAGE_LIKES", "POST_ENGAGEMENT", "QUALITY_CALL", "REACH", "LANDING_PAGE_VIEWS", "VISIT_INSTAGRAM_PROFILE", "VALUE", "THRUPLAY", "DERIVED_EVENTS", "APP_INSTALLS_AND_OFFSITE_CONVERSIONS", "CONVERSATIONS", "IN_APP_VALUE", "MESSAGING_PURCHASE_CONVERSION", "SUBSCRIBERS", "REMINDERS_SET", "MEANINGFUL_CALL_ATTEMPT", "PROFILE_VISIT", "PROFILE_AND_PAGE_ENGAGEMENT", "TWO_SECOND_CONTINUOUS_VIDEO_VIEWS", "ENGAGED_REACH", "ENGAGED_PAGE_VIEWS", "MESSAGING_DEEP_CONVERSATION_AND_FOLLOW", "ADVERTISER_SILOED_VALUE", "AUTOMATIC_OBJECTIVE", "MESSAGING_APPOINTMENT_CONVERSION" ], "type": "string" }, "MetaAdGroupPlatformConfigStatus": { "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "MuxAssetStatuses": { "description": "Mux asset statuses", "enum": [ "uploading", "created", "ready" ], "type": "string" }, "PageInfo": { "description": "Information about pagination in a connection.", "properties": { "end_cursor": { "description": "When paginating forwards, the cursor to continue.", "type": [ "string", "null" ] }, "has_next_page": { "description": "When paginating forwards, are there more items?", "type": "boolean" }, "has_previous_page": { "description": "When paginating backwards, are there more items?", "type": "boolean" }, "start_cursor": { "description": "When paginating backwards, the cursor to continue.", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" }, "Pagination": { "additionalProperties": false, "properties": { "current_page": { "description": "Current page number", "type": "number" }, "next_page": { "description": "Next page number", "nullable": true, "type": "number" }, "prev_page": { "description": "Previous page number", "nullable": true, "type": "number" }, "total_count": { "description": "Total number of records", "type": "number" }, "total_pages": { "description": "Total number of pages", "type": "number" } }, "required": [ "current_page", "total_pages", "next_page", "prev_page", "total_count" ], "type": "object" }, "Payment": { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "amount_after_fees": { "description": "How much the payment is for after fees", "example": 6.9, "type": "number" }, "application_fee": { "description": "The application fee charged on this payment.", "properties": { "amount": { "description": "The application fee amount.", "example": 6.9, "type": "number" }, "amount_captured": { "description": "The amount of the application fee that has been captured.", "example": 6.9, "type": "number" }, "amount_refunded": { "description": "The amount of the application fee that has been refunded.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the application fee was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the application fee." }, "id": { "description": "The unique identifier for the application fee.", "example": "apfee_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "amount", "amount_captured", "amount_refunded", "currency", "created_at" ], "type": [ "object", "null" ] }, "auto_refunded": { "description": "Whether this payment was auto refunded or not", "type": "boolean" }, "billing_address": { "description": "The address of the user who made the payment.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this payment, if any. Use this to map payments back to the checkout configuration that created them.", "type": [ "string", "null" ] }, "company": { "description": "The company for the payment.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "disputes": { "description": "The disputes attached to this payment. Null if the actor in context does not have the payment:dispute:read permission.", "items": { "description": "A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.", "properties": { "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "editable": { "description": "Whether the dispute evidence can still be edited and submitted.", "type": [ "boolean", "null" ] }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "needs_response_by": { "description": "The deadline by which dispute evidence must be submitted. Null if no response deadline is set.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "notes": { "description": "Additional freeform notes submitted by the company as part of the dispute evidence.", "example": "Customer used the product for 3 months before disputing.", "type": [ "string", "null" ] }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." } }, "required": [ "id", "amount", "currency", "status", "editable", "needs_response_by", "reason", "notes" ], "type": "object" }, "type": [ "array", "null" ] }, "failure_message": { "description": "If the payment failed, the reason for the failure.", "type": [ "string", "null" ] }, "financing_installments_count": { "description": "The number of financing installments for the payment. Present if the payment is a financing payment (e.g. Splitit, Klarna, etc.).", "example": 42, "type": [ "integer", "null" ] }, "financing_transactions": { "description": "The financing transactions attached to this payment. Present if the payment is a financing payment (e.g. Splitit, Klarna, etc.).", "items": { "description": "A payment transaction.", "properties": { "amount": { "description": "The amount of the payment transaction.", "example": 6.9, "type": "number" }, "created_at": { "description": "The date and time the payment transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment transaction.", "example": "ptx_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/PaymentTransactionStatuses", "description": "The status of the payment transaction." }, "transaction_type": { "$ref": "#/components/schemas/PaymentTransactionTypes", "description": "The type of the payment transaction." } }, "required": [ "id", "amount", "status", "created_at", "transaction_type" ], "type": "object" }, "type": "array" }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_attempt": { "description": "The time of the last payment attempt.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "phone_number": { "description": "The phone number associated with this membership.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status", "phone_number" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "The custom metadata stored on this payment. This will be copied over to the checkout configuration for which this payment was made", "type": [ "object", "null" ] }, "next_payment_attempt": { "description": "The time of the next schedule payment retry.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method": { "description": "The tokenized payment method reference used for this payment. Null if no token was used.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card" ], "type": [ "object", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "payments_failed": { "description": "The number of failed payment attempts for the payment.", "example": 42, "type": [ "integer", "null" ] }, "plan": { "description": "The plan attached to this payment.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] } }, "required": [ "id", "internal_notes", "metadata" ], "type": [ "object", "null" ] }, "product": { "description": "The product this payment was made for", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "route": { "description": "The URL slug used in the product's public link (e.g., 'my-product' in whop.com/company/my-product).", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "route", "metadata" ], "type": [ "object", "null" ] }, "promo_code": { "description": "The promo code used for this payment.", "properties": { "amount_off": { "description": "The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).", "example": 6.9, "type": "number" }, "base_currency": { "$ref": "#/components/schemas/Currencies", "description": "The monetary currency of the promo code." }, "code": { "description": "The specific code used to apply the promo at checkout.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" }, "number_of_intervals": { "description": "The number of months the promo is applied for.", "example": 42, "type": [ "integer", "null" ] }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The type (% or flat amount) of the promo." } }, "required": [ "id", "code", "amount_off", "base_currency", "promo_type", "number_of_intervals" ], "type": [ "object", "null" ] }, "refundable": { "description": "True only for payments that are `paid`, have not been fully refunded, and were processed by a payment processor that allows refunds.", "type": "boolean" }, "refunded_amount": { "description": "The payment refund amount(if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "refunded_at": { "description": "When the payment was refunded (if applicable).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "resolutions": { "description": "The resolution center cases opened by the customer on this payment. Null if the actor in context does not have the payment:resolution_center_case:read permission.", "items": { "description": "A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.", "properties": { "customer_appealed": { "description": "Whether the customer has filed an appeal after the initial resolution decision.", "type": "boolean" }, "customer_response_actions": { "description": "The list of actions currently available to the customer.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseCustomerResponses" }, "type": "array" }, "due_date": { "description": "The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution.", "example": "reso_xxxxxxxxxxxxx", "type": "string" }, "issue": { "$ref": "#/components/schemas/ResolutionCenterCaseIssueTypes", "description": "The category of the dispute." }, "merchant_appealed": { "description": "Whether the merchant has filed an appeal after the initial resolution decision.", "type": "boolean" }, "merchant_response_actions": { "description": "The list of actions currently available to the merchant.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseMerchantResponses" }, "type": "array" }, "platform_response_actions": { "description": "The list of actions currently available to the Whop platform for moderating this resolution.", "items": { "$ref": "#/components/schemas/ResolutionCenterCasePlatformResponses" }, "type": "array" }, "status": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses", "description": "The current status of the resolution case, indicating which party needs to respond or if the case is closed." } }, "required": [ "id", "status", "due_date", "issue", "customer_appealed", "merchant_appealed", "customer_response_actions", "merchant_response_actions", "platform_response_actions" ], "type": "object" }, "type": [ "array", "null" ] }, "retryable": { "description": "True when the payment status is `open` and its membership is in one of the retry-eligible states (`active`, `trialing`, `completed`, or `past_due`); otherwise false. Used to decide if Whop can attempt the charge again.", "type": "boolean" }, "settlement_amount": { "description": "The total amount charged to the customer for this payment, including taxes and after any discounts. In the currency specified by the currency field.", "example": 6.9, "type": "number" }, "settlement_currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "settlement_exchange_rate": { "description": "Deprecated. Always returns null.", "example": 6.9, "type": [ "number", "null" ] }, "status": { "description": "The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').", "oneOf": [ { "$ref": "#/components/schemas/ReceiptStatus" }, { "type": "null" } ] }, "substatus": { "$ref": "#/components/schemas/FriendlyReceiptStatus", "description": "The friendly status of the payment." }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "tax_amount": { "description": "The calculated amount of the sales/VAT tax (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "tax_behavior": { "description": "The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "tax_refunded_amount": { "description": "The amount of tax that has been refunded (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the payment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] }, "voidable": { "description": "True when the payment is tied to a membership in `past_due`, the payment status is `open`, and the processor allows voiding payments; otherwise false.", "type": "boolean" } }, "required": [ "id", "status", "substatus", "refundable", "retryable", "voidable", "created_at", "updated_at", "paid_at", "last_payment_attempt", "next_payment_attempt", "dispute_alerted_at", "refunded_at", "plan", "product", "user", "membership", "member", "payment_method", "company", "promo_code", "currency", "settlement_currency", "total", "subtotal", "usd_total", "refunded_amount", "auto_refunded", "amount_after_fees", "application_fee", "card_brand", "card_last4", "billing_address", "payment_method_type", "billing_reason", "payments_failed", "tax_amount", "tax_behavior", "failure_message", "metadata", "checkout_configuration_id", "settlement_amount", "settlement_exchange_rate", "tax_refunded_amount", "financing_installments_count", "financing_transactions", "disputes", "resolutions" ], "type": "object" }, "PaymentListItem": { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "amount_after_fees": { "description": "How much the payment is for after fees", "example": 6.9, "type": "number" }, "application_fee": { "description": "The application fee charged on this payment.", "properties": { "amount": { "description": "The application fee amount.", "example": 6.9, "type": "number" }, "amount_captured": { "description": "The amount of the application fee that has been captured.", "example": 6.9, "type": "number" }, "amount_refunded": { "description": "The amount of the application fee that has been refunded.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the application fee was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the application fee." }, "id": { "description": "The unique identifier for the application fee.", "example": "apfee_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "amount", "amount_captured", "amount_refunded", "currency", "created_at" ], "type": [ "object", "null" ] }, "auto_refunded": { "description": "Whether this payment was auto refunded or not", "type": "boolean" }, "billing_address": { "description": "The address of the user who made the payment.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this payment, if any. Use this to map payments back to the checkout configuration that created them.", "type": [ "string", "null" ] }, "company": { "description": "The company for the payment.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "failure_message": { "description": "If the payment failed, the reason for the failure.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_attempt": { "description": "The time of the last payment attempt.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "phone_number": { "description": "The phone number associated with this membership.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status", "phone_number" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "The custom metadata stored on this payment. This will be copied over to the checkout configuration for which this payment was made", "type": [ "object", "null" ] }, "next_payment_attempt": { "description": "The time of the next schedule payment retry.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method": { "description": "The tokenized payment method reference used for this payment. Null if no token was used.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card" ], "type": [ "object", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "payments_failed": { "description": "The number of failed payment attempts for the payment.", "example": 42, "type": [ "integer", "null" ] }, "plan": { "description": "The plan attached to this payment.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] } }, "required": [ "id", "internal_notes", "metadata" ], "type": [ "object", "null" ] }, "product": { "description": "The product this payment was made for", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "route": { "description": "The URL slug used in the product's public link (e.g., 'my-product' in whop.com/company/my-product).", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "route", "metadata" ], "type": [ "object", "null" ] }, "promo_code": { "description": "The promo code used for this payment.", "properties": { "amount_off": { "description": "The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).", "example": 6.9, "type": "number" }, "base_currency": { "$ref": "#/components/schemas/Currencies", "description": "The monetary currency of the promo code." }, "code": { "description": "The specific code used to apply the promo at checkout.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" }, "number_of_intervals": { "description": "The number of months the promo is applied for.", "example": 42, "type": [ "integer", "null" ] }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The type (% or flat amount) of the promo." } }, "required": [ "id", "code", "amount_off", "base_currency", "promo_type", "number_of_intervals" ], "type": [ "object", "null" ] }, "refundable": { "description": "True only for payments that are `paid`, have not been fully refunded, and were processed by a payment processor that allows refunds.", "type": "boolean" }, "refunded_amount": { "description": "The payment refund amount(if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "refunded_at": { "description": "When the payment was refunded (if applicable).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "retryable": { "description": "True when the payment status is `open` and its membership is in one of the retry-eligible states (`active`, `trialing`, `completed`, or `past_due`); otherwise false. Used to decide if Whop can attempt the charge again.", "type": "boolean" }, "settlement_currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "status": { "description": "The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').", "oneOf": [ { "$ref": "#/components/schemas/ReceiptStatus" }, { "type": "null" } ] }, "substatus": { "$ref": "#/components/schemas/FriendlyReceiptStatus", "description": "The friendly status of the payment." }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "tax_amount": { "description": "The calculated amount of the sales/VAT tax (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "tax_behavior": { "description": "The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the payment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] }, "voidable": { "description": "True when the payment is tied to a membership in `past_due`, the payment status is `open`, and the processor allows voiding payments; otherwise false.", "type": "boolean" } }, "required": [ "id", "status", "substatus", "refundable", "retryable", "voidable", "created_at", "updated_at", "paid_at", "last_payment_attempt", "next_payment_attempt", "dispute_alerted_at", "refunded_at", "plan", "product", "user", "membership", "member", "payment_method", "company", "promo_code", "currency", "settlement_currency", "total", "subtotal", "usd_total", "refunded_amount", "auto_refunded", "amount_after_fees", "application_fee", "card_brand", "card_last4", "billing_address", "payment_method_type", "billing_reason", "payments_failed", "tax_amount", "tax_behavior", "failure_message", "metadata", "checkout_configuration_id" ], "type": "object" }, "PaymentMethod": { "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A saved payment method with no type-specific details available.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "BasePaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type" ], "title": "BasePaymentMethod", "type": "object" }, { "description": "A saved card payment method, including brand, last four digits, and expiration details.", "properties": { "card": { "description": "The card-specific details for this payment method, including brand, last four digits, and expiration.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CardPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "card" ], "title": "CardPaymentMethod", "type": "object" }, { "description": "A saved US bank account payment method, including bank name, last four digits, and account type.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "UsBankAccountPaymentMethod", "description": "The typename of this object", "type": "string" }, "us_bank_account": { "description": "The bank account-specific details for this payment method, including bank name and last four digits.", "properties": { "account_type": { "description": "The type of bank account (e.g., checking, savings).", "example": "checking", "type": "string" }, "bank_name": { "description": "The name of the financial institution holding the account.", "example": "Chase", "type": "string" }, "last4": { "description": "The last four digits of the bank account number.", "example": "6789", "type": "string" } }, "required": [ "bank_name", "last4", "account_type" ], "type": "object" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "us_bank_account" ], "title": "UsBankAccountPaymentMethod", "type": "object" }, { "description": "A saved Cash App payment method, including the buyer's cashtag and unique identifier.", "properties": { "cashapp": { "description": "The Cash App-specific details for this payment method, including cashtag and buyer ID.", "properties": { "buyer_id": { "description": "The unique and immutable identifier assigned by Cash App to the buyer. Null if not available.", "example": "BUYER_abc123", "type": [ "string", "null" ] }, "cashtag": { "description": "The public cashtag handle of the buyer on Cash App. Null if not available.", "example": "$jacksmith", "type": [ "string", "null" ] } }, "required": [ "buyer_id", "cashtag" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CashappPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "cashapp" ], "title": "CashappPaymentMethod", "type": "object" }, { "description": "A saved iDEAL payment method, including the customer's bank name and BIC code.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "ideal": { "description": "The iDEAL-specific details for this payment method, including bank name and BIC.", "properties": { "bank": { "description": "The name of the customer's bank used for the iDEAL transaction. Null if not available.", "example": "ing", "type": [ "string", "null" ] }, "bic": { "description": "The Bank Identifier Code (BIC/SWIFT) of the customer's bank. Null if not available.", "example": "INGBNL2A", "type": [ "string", "null" ] } }, "required": [ "bank", "bic" ], "type": "object" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "IdealPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "ideal" ], "title": "IdealPaymentMethod", "type": "object" }, { "description": "A saved SEPA Direct Debit payment method, including the bank code, country, and last four IBAN digits.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "sepa_debit": { "description": "The SEPA Direct Debit-specific details for this payment method, including bank code and last four IBAN digits.", "properties": { "bank_code": { "description": "The bank code of the financial institution associated with this SEPA account. Null if not available.", "example": "37040044", "type": [ "string", "null" ] }, "branch_code": { "description": "The branch code of the financial institution associated with this SEPA account. Null if not available.", "example": "0532", "type": [ "string", "null" ] }, "country": { "description": "The two-letter ISO country code where the bank account is located. Null if not available.", "example": "DE", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the IBAN associated with this SEPA account. Null if not available.", "example": "3000", "type": [ "string", "null" ] } }, "required": [ "bank_code", "branch_code", "country", "last4" ], "type": "object" }, "typename": { "const": "SepaDebitPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "sepa_debit" ], "title": "SepaDebitPaymentMethod", "type": "object" } ], "type": "object" }, "PaymentMethodListItem": { "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A saved payment method with no type-specific details available.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "BasePaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type" ], "title": "BasePaymentMethod", "type": "object" }, { "description": "A saved card payment method, including brand, last four digits, and expiration details.", "properties": { "card": { "description": "The card-specific details for this payment method, including brand, last four digits, and expiration.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CardPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "card" ], "title": "CardPaymentMethod", "type": "object" }, { "description": "A saved US bank account payment method, including bank name, last four digits, and account type.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "UsBankAccountPaymentMethod", "description": "The typename of this object", "type": "string" }, "us_bank_account": { "description": "The bank account-specific details for this payment method, including bank name and last four digits.", "properties": { "account_type": { "description": "The type of bank account (e.g., checking, savings).", "example": "checking", "type": "string" }, "bank_name": { "description": "The name of the financial institution holding the account.", "example": "Chase", "type": "string" }, "last4": { "description": "The last four digits of the bank account number.", "example": "6789", "type": "string" } }, "required": [ "bank_name", "last4", "account_type" ], "type": "object" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "us_bank_account" ], "title": "UsBankAccountPaymentMethod", "type": "object" }, { "description": "A saved Cash App payment method, including the buyer's cashtag and unique identifier.", "properties": { "cashapp": { "description": "The Cash App-specific details for this payment method, including cashtag and buyer ID.", "properties": { "buyer_id": { "description": "The unique and immutable identifier assigned by Cash App to the buyer. Null if not available.", "example": "BUYER_abc123", "type": [ "string", "null" ] }, "cashtag": { "description": "The public cashtag handle of the buyer on Cash App. Null if not available.", "example": "$jacksmith", "type": [ "string", "null" ] } }, "required": [ "buyer_id", "cashtag" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CashappPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "cashapp" ], "title": "CashappPaymentMethod", "type": "object" }, { "description": "A saved iDEAL payment method, including the customer's bank name and BIC code.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "ideal": { "description": "The iDEAL-specific details for this payment method, including bank name and BIC.", "properties": { "bank": { "description": "The name of the customer's bank used for the iDEAL transaction. Null if not available.", "example": "ing", "type": [ "string", "null" ] }, "bic": { "description": "The Bank Identifier Code (BIC/SWIFT) of the customer's bank. Null if not available.", "example": "INGBNL2A", "type": [ "string", "null" ] } }, "required": [ "bank", "bic" ], "type": "object" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "IdealPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "ideal" ], "title": "IdealPaymentMethod", "type": "object" }, { "description": "A saved SEPA Direct Debit payment method, including the bank code, country, and last four IBAN digits.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "sepa_debit": { "description": "The SEPA Direct Debit-specific details for this payment method, including bank code and last four IBAN digits.", "properties": { "bank_code": { "description": "The bank code of the financial institution associated with this SEPA account. Null if not available.", "example": "37040044", "type": [ "string", "null" ] }, "branch_code": { "description": "The branch code of the financial institution associated with this SEPA account. Null if not available.", "example": "0532", "type": [ "string", "null" ] }, "country": { "description": "The two-letter ISO country code where the bank account is located. Null if not available.", "example": "DE", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the IBAN associated with this SEPA account. Null if not available.", "example": "3000", "type": [ "string", "null" ] } }, "required": [ "bank_code", "branch_code", "country", "last4" ], "type": "object" }, "typename": { "const": "SepaDebitPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "sepa_debit" ], "title": "SepaDebitPaymentMethod", "type": "object" } ], "type": "object" }, "PaymentMethodTypes": { "description": "The different types of payment methods that can be used.", "enum": [ "acss_debit", "affirm", "afterpay_clearpay", "alipay", "alma", "amazon_pay", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "billie", "bizum", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "cashapp", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "efecty", "eps", "eu_bank_transfer", "fpx", "gb_bank_transfer", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "link", "mb_way", "m_pesa", "mercado_pago", "mobilepay", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nz_bank_account", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypay", "payto", "pix", "platform_balance", "promptpay", "qris", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tamara", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "vipps", "webpay", "wechat_pay", "yape", "zip", "coinflow", "unknown" ], "type": "string" }, "PaymentProviders": { "description": "The different payment providers.", "enum": [ "stripe", "coinbase", "paypal", "apple", "sezzle", "splitit", "platform_balance", "multi_psp", "adyen", "claritypay", "checkout_dot_com", "airwallex", "coinflow", "sequra", "dlocal" ], "type": "string" }, "PaymentTransactionStatuses": { "description": "The different statuses a payment transaction can be in.", "enum": [ "succeeded", "declined", "error", "pending", "created", "expired", "won", "rejected", "lost", "prevented", "canceled" ], "type": "string" }, "PaymentTransactionTypes": { "description": "The different types of payment transactions.", "enum": [ "purchase", "authorize", "capture", "refund", "canceled", "verify", "chargeback", "pre_chargeback", "three_d_secure", "fraud_screening", "authorization", "installment" ], "type": "string" }, "PaymentsApprovalStatuses": { "description": "The different approval statuses an account can have.", "enum": [ "pending", "approved", "monitoring", "rejected" ], "type": "string" }, "PayoutAccount": { "description": "An object representing an account used for payouts.", "properties": { "address": { "description": "The physical address associated with this payout account", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "state", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "The company's legal name", "type": [ "string", "null" ] }, "business_representative": { "description": "The business representative for this payout account", "properties": { "date_of_birth": { "description": "The date of birth of the business representative in ISO 8601 format (YYYY-MM-DD).", "type": [ "string", "null" ] }, "first_name": { "description": "The first name of the business representative.", "type": [ "string", "null" ] }, "last_name": { "description": "The last name of the business representative.", "type": [ "string", "null" ] }, "middle_name": { "description": "The middle name of the business representative.", "type": [ "string", "null" ] } }, "required": [ "date_of_birth", "first_name", "middle_name", "last_name" ], "type": [ "object", "null" ] }, "email": { "description": "The email address of the representative", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payout account.", "example": "poact_xxxxxxxxxxxx", "type": "string" }, "latest_verification": { "description": "The latest verification for the connected account.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": [ "object", "null" ] }, "phone": { "description": "The business representative's phone", "type": [ "string", "null" ] }, "status": { "description": "The granular calculated status of the payout account reflecting its current KYC and withdrawal readiness state.", "oneOf": [ { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses" }, { "type": "null" } ] } }, "required": [ "id", "status", "business_name", "phone", "email", "business_representative", "address", "latest_verification" ], "type": "object" }, "PayoutAccountCalculatedStatuses": { "description": "The granular calculated statuses reflecting payout account KYC and withdrawal readiness.", "enum": [ "connected", "disabled", "action_required", "pending_verification", "verification_failed", "not_started" ], "type": "string" }, "PayoutDestinationCategory": { "description": "The category of a payout destination.", "enum": [ "crypto", "rtp", "next_day_bank", "bank_wire", "digital_wallet", "unknown" ], "type": "string" }, "PayoutErrorCodes": { "description": "The different error codes a payout can be in.", "enum": [ "account_closed", "account_does_not_exist", "account_information_invalid", "account_number_invalid_region", "account_frozen", "account_lookup_failed", "account_not_found", "amount_out_of_bounds", "attributes_not_validated", "b2b_payments_prohibited", "bank_statement_required", "compliance_review", "currency_not_supported", "deposit_canceled", "deposit_failed", "deposit_rejected", "destination_unavailable", "exceeded_account_limit", "expired_quote", "generic_payout_error", "technical_problem", "identification_number_invalid", "invalid_account_number", "invalid_bank_code", "invalid_beneficiary", "invalid_mailing_address", "invalid_branch_number", "invalid_branch_code", "invalid_phone_number", "invalid_routing_number", "invalid_swift_code", "invalid_company_details", "manual_cancelation", "misc_error", "missing_city_and_country", "missing_phone_number", "missing_remittance_info", "payee_name_invalid", "receiving_account_locked", "rejected_by_compliance", "rtp_not_supported", "non_transaction_account", "source_token_insufficient_funds", "ssn_invalid", "wallet_screenshot_required", "unsupported_region", "payout_provider_timeout" ], "type": "string" }, "PayoutMethod": { "description": "A configured payout destination where a user receives earned funds, such as a bank account or digital wallet.", "properties": { "account_reference": { "description": "A masked identifier for the payout destination, such as the last four digits of a bank account or an email address. Null if no reference is available.", "example": "****1234", "type": [ "string", "null" ] }, "company": { "description": "The company associated with this payout destination. Null if not linked to a specific company.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payout token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code that payouts are delivered in for this destination.", "example": "USD", "type": "string" }, "destination": { "description": "The payout destination configuration linked to this token. Null if not yet configured.", "properties": { "category": { "$ref": "#/components/schemas/PayoutDestinationCategory", "description": "The category of the payout destination" }, "country_code": { "description": "The country code of the payout destination", "type": "string" }, "name": { "description": "The name of the payer associated with the payout destination", "type": "string" } }, "required": [ "country_code", "category", "name" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the payout token.", "example": "potk_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "The name of the bank or financial institution receiving payouts. Null if not applicable or not provided.", "example": "Chase Bank", "type": [ "string", "null" ] }, "is_default": { "description": "Whether this is the default payout destination for the associated payout account.", "type": "boolean" }, "nickname": { "description": "A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.", "example": "My Business Account", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "company", "nickname", "currency", "is_default", "account_reference", "institution_name", "destination" ], "type": "object" }, "PayoutMethodListItem": { "description": "A configured payout destination where a user receives earned funds, such as a bank account or digital wallet.", "properties": { "account_reference": { "description": "A masked identifier for the payout destination, such as the last four digits of a bank account or an email address. Null if no reference is available.", "example": "****1234", "type": [ "string", "null" ] }, "company": { "description": "The company associated with this payout destination. Null if not linked to a specific company.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payout token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code that payouts are delivered in for this destination.", "example": "USD", "type": "string" }, "destination": { "description": "The payout destination configuration linked to this token. Null if not yet configured.", "properties": { "category": { "$ref": "#/components/schemas/PayoutDestinationCategory", "description": "The category of the payout destination" }, "country_code": { "description": "The country code of the payout destination", "type": "string" }, "name": { "description": "The name of the payer associated with the payout destination", "type": "string" } }, "required": [ "country_code", "category", "name" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the payout token.", "example": "potk_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "The name of the bank or financial institution receiving payouts. Null if not applicable or not provided.", "example": "Chase Bank", "type": [ "string", "null" ] }, "is_default": { "description": "Whether this is the default payout destination for the associated payout account.", "type": "boolean" }, "nickname": { "description": "A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.", "example": "My Business Account", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "company", "nickname", "currency", "is_default", "account_reference", "institution_name", "destination" ], "type": "object" }, "PermissionSystemRoles": { "description": "The different system roles that can be assigned.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser" ], "type": "string" }, "Plan": { "properties": { "account": { "description": "The account that sells this plan, an object with an id and title. Null for standalone invoice plans", "nullable": true, "type": "object" }, "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing", "type": "boolean" }, "billing_period": { "description": "The number of days between recurring charges. Null for one-time plans", "nullable": true, "type": "number" }, "collect_tax": { "description": "Whether tax is collected on purchases of this plan", "type": "boolean" }, "created_at": { "description": "When the plan was created, as an ISO 8601 timestamp", "type": "string" }, "currency": { "description": "The three-letter ISO currency code all prices on this plan are denominated in", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "type": "string" }, "custom_fields": { "description": "Custom input fields displayed on the checkout form, objects with id, field_type, name, order, placeholder and required", "type": "array" }, "description": { "description": "A text description of the plan visible to customers", "nullable": true, "type": "string" }, "expiration_days": { "description": "The number of days until the membership expires, for expiration-based plans", "nullable": true, "type": "number" }, "id": { "description": "The ID of the plan, which will look like plan_*************", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's currency", "type": "number" }, "internal_notes": { "description": "Private notes visible only to authorized team members", "nullable": true, "type": "string" }, "invoice": { "description": "The invoice this plan was generated for, an object with an id. Null unless the plan was created for an invoice", "nullable": true, "type": "object" }, "member_count": { "description": "The number of active memberships on this plan. Only visible to authorized team members", "nullable": true, "type": "number" }, "metadata": { "description": "Custom key-value pairs stored on the plan", "nullable": true, "type": "object" }, "payment_method_configuration": { "description": "The explicit payment method configuration for the plan, an object with enabled, disabled and include_platform_defaults. Null if the plan uses default settings", "nullable": true, "type": "object" }, "plan_type": { "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments", "enum": [ "renewal", "one_time" ], "type": "string" }, "product": { "description": "The product this plan belongs to, an object with an id and title. Null for standalone plans", "nullable": true, "type": "object" }, "purchase_url": { "description": "The full URL where customers can purchase this plan directly", "type": "string" }, "release_method": { "description": "The method used to sell this plan, e.g. 'buy_now' or 'waitlist'", "enum": [ "buy_now", "waitlist" ], "type": "string" }, "renewal_price": { "description": "The recurring price charged every billing period in the plan's currency", "type": "number" }, "split_pay_required_payments": { "description": "The number of installment payments required before the subscription pauses", "nullable": true, "type": "number" }, "stock": { "description": "The number of units available for purchase. Only visible to authorized team members", "nullable": true, "type": "number" }, "tax_type": { "description": "How tax is handled for this plan: 'inclusive', 'exclusive', or 'unspecified'", "type": "string" }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Null means the plan inherits the account default", "enum": [ "mandate_challenge", "frictionless" ], "nullable": true, "type": "string" }, "title": { "description": "The display name of the plan shown to customers", "nullable": true, "type": "string" }, "trial_period_days": { "description": "The number of free trial days before the first charge on a recurring plan", "nullable": true, "type": "number" }, "unlimited_stock": { "description": "Whether the plan has unlimited stock", "type": "boolean" }, "updated_at": { "description": "When the plan was last updated, as an ISO 8601 timestamp", "type": "string" }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view", "enum": [ "visible", "hidden", "archived", "quick_link" ], "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "plan_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "stock", "unlimited_stock", "split_pay_required_payments", "adaptive_pricing_enabled", "payment_method_configuration", "tax_type", "collect_tax", "custom_fields" ], "type": "object" }, "PlanListItem": { "properties": { "account": { "description": "The account that sells this plan, an object with an id and title. Null for standalone invoice plans", "nullable": true, "type": "object" }, "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing", "type": "boolean" }, "billing_period": { "description": "The number of days between recurring charges. Null for one-time plans", "nullable": true, "type": "number" }, "created_at": { "description": "When the plan was created, as an ISO 8601 timestamp", "type": "string" }, "currency": { "description": "The three-letter ISO currency code all prices on this plan are denominated in", "type": "string" }, "description": { "description": "A text description of the plan visible to customers", "nullable": true, "type": "string" }, "expiration_days": { "description": "The number of days until the membership expires, for expiration-based plans", "nullable": true, "type": "number" }, "id": { "description": "The ID of the plan, which will look like plan_*************", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's currency", "type": "number" }, "internal_notes": { "description": "Private notes visible only to authorized team members", "nullable": true, "type": "string" }, "invoice": { "description": "The invoice this plan was generated for, an object with an id. Null unless the plan was created for an invoice", "nullable": true, "type": "object" }, "member_count": { "description": "The number of active memberships on this plan. Only visible to authorized team members", "nullable": true, "type": "number" }, "metadata": { "description": "Custom key-value pairs stored on the plan", "nullable": true, "type": "object" }, "payment_method_configuration": { "description": "The explicit payment method configuration for the plan, an object with enabled, disabled and include_platform_defaults. Null if the plan uses default settings", "nullable": true, "type": "object" }, "plan_type": { "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments", "type": "string" }, "product": { "description": "The product this plan belongs to, an object with an id and title. Null for standalone plans", "nullable": true, "type": "object" }, "purchase_url": { "description": "The full URL where customers can purchase this plan directly", "type": "string" }, "release_method": { "description": "The method used to sell this plan, e.g. 'buy_now' or 'waitlist'", "type": "string" }, "renewal_price": { "description": "The recurring price charged every billing period in the plan's currency", "type": "number" }, "split_pay_required_payments": { "description": "The number of installment payments required before the subscription pauses", "nullable": true, "type": "number" }, "stock": { "description": "The number of units available for purchase. Only visible to authorized team members", "nullable": true, "type": "number" }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Null means the plan inherits the account default", "nullable": true, "type": "string" }, "title": { "description": "The display name of the plan shown to customers", "nullable": true, "type": "string" }, "trial_period_days": { "description": "The number of free trial days before the first charge on a recurring plan", "nullable": true, "type": "number" }, "unlimited_stock": { "description": "Whether the plan has unlimited stock", "type": "boolean" }, "updated_at": { "description": "When the plan was last updated, as an ISO 8601 timestamp", "type": "string" }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "plan_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "stock", "unlimited_stock", "split_pay_required_payments", "adaptive_pricing_enabled", "payment_method_configuration" ], "type": "object" }, "PlanThreeDsLevels": { "description": "The 3D Secure behavior for a plan.", "enum": [ "mandate_challenge", "frictionless" ], "type": "string" }, "PlanTypes": { "description": "The type of plan that can be attached to a product", "enum": [ "renewal", "one_time" ], "type": "string" }, "Product": { "description": "A product is a digital good or service sold on Whop. Products contain plans for pricing and experiences for content delivery.", "properties": { "company": { "description": "The company this product belongs to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "route", "title" ], "type": "object" }, "created_at": { "description": "The datetime the product was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "custom_cta": { "$ref": "#/components/schemas/CustomCtas", "description": "The call-to-action button label displayed on the product's purchase page (e.g., 'join', 'buy', 'subscribe')." }, "custom_cta_url": { "description": "An optional URL that the call-to-action button links to instead of the default checkout flow. Null if no custom URL is set.", "example": "https://example.com/signup", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "A custom text label that appears on the customer's bank or credit card statement for purchases of this product. Maximum 22 characters, including the required prefix WHOP*.", "example": "PICKAXE", "type": [ "string", "null" ] }, "description": { "description": "A brief summary of what the product offers, displayed on product pages and search results.", "example": "Track your revenue, members, and growth in real time.", "type": [ "string", "null" ] }, "external_identifier": { "description": "A unique identifier used to create or update products via the API. When provided on product creation endpoints, an existing product with this identifier will be updated instead of creating a new one.", "example": "ext_prod_12345", "type": [ "string", "null" ] }, "gallery_images": { "description": "The gallery images for this product, ordered by position.", "items": { "description": "Represents an image attachment", "properties": { "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "url" ], "type": "object" }, "type": "array" }, "global_affiliate_percentage": { "description": "The commission rate (as a percentage) that affiliates earn on sales through the Whop marketplace global affiliate program. Null if the program is not active.", "example": 6.9, "type": [ "number", "null" ] }, "global_affiliate_status": { "$ref": "#/components/schemas/GlobalAffiliateStatuses", "description": "The enrollment status of this product in the Whop marketplace global affiliate program." }, "headline": { "description": "A short marketing headline displayed prominently on the product's product page.", "example": "Real-time data analytics for creators", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "member_affiliate_percentage": { "description": "The commission rate (as a percentage) that existing members earn when referring new customers through the member affiliate program. Null if the program is not active.", "example": 6.9, "type": [ "number", "null" ] }, "member_affiliate_status": { "$ref": "#/components/schemas/GlobalAffiliateStatuses", "description": "The enrollment status of this product in the member affiliate program." }, "member_count": { "description": "The number of users who currently hold an active membership to this product. Returns 0 if the company has disabled public member counts.", "example": 42, "type": "integer" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "owner_user": { "description": "The user who owns the company that sells this product.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "product_tax_code": { "description": "The tax classification code applied to purchases of this product for sales tax calculation. Null if no tax code is assigned.", "properties": { "id": { "description": "The unique identifier for the product tax code.", "example": "ptc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The human-readable name of this tax classification (e.g., 'Digital - SaaS').", "example": "Digital - SaaS", "type": "string" }, "product_type": { "$ref": "#/components/schemas/ProductTaxCodeProductTypes", "description": "The broad product category this tax code covers (e.g., physical goods, digital services)." } }, "required": [ "id", "name", "product_type" ], "type": [ "object", "null" ] }, "published_reviews_count": { "description": "The total number of published customer reviews for this product's company.", "example": 42, "type": "integer" }, "route": { "description": "The URL slug used in the product's public link (e.g., 'my-product' in whop.com/company/my-product).", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" }, "updated_at": { "description": "The datetime the product was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verified": { "description": "Whether this company has been verified by Whop's trust and safety team.", "type": "boolean" }, "visibility": { "$ref": "#/components/schemas/Visibility", "description": "Controls whether the product is visible to customers. When set to 'hidden', the product is only accessible via direct link." } }, "required": [ "id", "title", "visibility", "headline", "verified", "created_at", "updated_at", "member_count", "route", "published_reviews_count", "external_identifier", "metadata", "description", "custom_cta", "custom_cta_url", "custom_statement_descriptor", "global_affiliate_percentage", "global_affiliate_status", "member_affiliate_percentage", "member_affiliate_status", "gallery_images", "product_tax_code", "owner_user", "company" ], "type": "object" }, "ProductListItem": { "description": "A product is a digital good or service sold on Whop. Products contain plans for pricing and experiences for content delivery.", "properties": { "created_at": { "description": "The datetime the product was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "external_identifier": { "description": "A unique identifier used to create or update products via the API. When provided on product creation endpoints, an existing product with this identifier will be updated instead of creating a new one.", "example": "ext_prod_12345", "type": [ "string", "null" ] }, "headline": { "description": "A short marketing headline displayed prominently on the product's product page.", "example": "Real-time data analytics for creators", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "member_count": { "description": "The number of users who currently hold an active membership to this product. Returns 0 if the company has disabled public member counts.", "example": 42, "type": "integer" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "published_reviews_count": { "description": "The total number of published customer reviews for this product's company.", "example": 42, "type": "integer" }, "route": { "description": "The URL slug used in the product's public link (e.g., 'my-product' in whop.com/company/my-product).", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" }, "updated_at": { "description": "The datetime the product was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verified": { "description": "Whether this company has been verified by Whop's trust and safety team.", "type": "boolean" }, "visibility": { "$ref": "#/components/schemas/Visibility", "description": "Controls whether the product is visible to customers. When set to 'hidden', the product is only accessible via direct link." } }, "required": [ "id", "title", "visibility", "headline", "verified", "created_at", "updated_at", "member_count", "route", "published_reviews_count", "external_identifier", "metadata" ], "type": "object" }, "ProductTaxCodeProductTypes": { "description": "The product_type of the ProductTaxCode", "enum": [ "physical", "digital", "services" ], "type": "string" }, "PromoCode": { "description": "A promo code applies a discount to a plan during checkout. Promo codes can be percentage-based or fixed-amount, and can have usage limits and expiration dates.", "properties": { "amount_off": { "description": "The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).", "example": 6.9, "type": "number" }, "churned_users_only": { "description": "Restricts promo use to only users who have churned from the company before.", "type": "boolean" }, "code": { "description": "The specific code used to apply the promo at checkout.", "type": [ "string", "null" ] }, "company": { "description": "The company for the promo code.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the promo code was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The monetary currency of the promo code." }, "duration": { "description": "The duration of the promo.", "oneOf": [ { "$ref": "#/components/schemas/PromoDurations" }, { "type": "null" } ] }, "existing_memberships_only": { "description": "Restricts promo use to only be applied to already purchased memberships.", "type": "boolean" }, "expires_at": { "description": "The date/time of when the promo expires.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" }, "new_users_only": { "description": "Restricts promo use to only users who have never purchased from the company before.", "type": "boolean" }, "one_per_customer": { "description": "Restricts promo use to only be applied once per customer.", "type": "boolean" }, "product": { "description": "The product this promo code applies to", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "promo_duration_months": { "description": "The number of months the promo is applied for.", "example": 42, "type": [ "integer", "null" ] }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The type (% or flat amount) of the promo." }, "status": { "$ref": "#/components/schemas/PromoCodeStatus", "description": "Indicates if the promo code is live or disabled." }, "stock": { "description": "The quantity limit on the number of uses.", "example": 42, "type": "integer" }, "unlimited_stock": { "description": "Whether or not the promo code has unlimited stock.", "type": "boolean" }, "uses": { "description": "The amount of times the promo codes has been used.", "example": 42, "type": "integer" } }, "required": [ "id", "amount_off", "currency", "churned_users_only", "code", "created_at", "existing_memberships_only", "duration", "expires_at", "new_users_only", "promo_duration_months", "one_per_customer", "product", "promo_type", "status", "stock", "unlimited_stock", "uses", "company" ], "type": "object" }, "PromoCodeListItem": { "description": "A promo code applies a discount to a plan during checkout. Promo codes can be percentage-based or fixed-amount, and can have usage limits and expiration dates.", "properties": { "amount_off": { "description": "The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).", "example": 6.9, "type": "number" }, "churned_users_only": { "description": "Restricts promo use to only users who have churned from the company before.", "type": "boolean" }, "code": { "description": "The specific code used to apply the promo at checkout.", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the promo code was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The monetary currency of the promo code." }, "duration": { "description": "The duration of the promo.", "oneOf": [ { "$ref": "#/components/schemas/PromoDurations" }, { "type": "null" } ] }, "existing_memberships_only": { "description": "Restricts promo use to only be applied to already purchased memberships.", "type": "boolean" }, "expires_at": { "description": "The date/time of when the promo expires.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" }, "new_users_only": { "description": "Restricts promo use to only users who have never purchased from the company before.", "type": "boolean" }, "one_per_customer": { "description": "Restricts promo use to only be applied once per customer.", "type": "boolean" }, "product": { "description": "The product this promo code applies to", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "promo_duration_months": { "description": "The number of months the promo is applied for.", "example": 42, "type": [ "integer", "null" ] }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The type (% or flat amount) of the promo." }, "status": { "$ref": "#/components/schemas/PromoCodeStatus", "description": "Indicates if the promo code is live or disabled." }, "stock": { "description": "The quantity limit on the number of uses.", "example": 42, "type": "integer" }, "unlimited_stock": { "description": "Whether or not the promo code has unlimited stock.", "type": "boolean" }, "uses": { "description": "The amount of times the promo codes has been used.", "example": 42, "type": "integer" } }, "required": [ "id", "amount_off", "currency", "churned_users_only", "code", "created_at", "existing_memberships_only", "duration", "expires_at", "new_users_only", "promo_duration_months", "one_per_customer", "product", "promo_type", "status", "stock", "unlimited_stock", "uses" ], "type": "object" }, "PromoCodeStatus": { "description": "Statuses for promo codes", "enum": [ "active", "inactive", "archived" ], "type": "string" }, "PromoCodeUpdateStatus": { "description": "Statuses that can be applied to promo codes through update operations.", "enum": [ "active", "inactive" ], "type": "string" }, "PromoDurations": { "description": "The duration setting for the promo code", "enum": [ "forever", "once", "repeating" ], "type": "string" }, "PromoTypes": { "description": "The type of promo code used to discount a plan", "enum": [ "percentage", "flat_amount" ], "type": "string" }, "Reaction": { "description": "A single reaction left by a user on a feed post, such as a like or emoji.", "properties": { "emoji": { "description": "The emoji used for this reaction in shortcode format. Null if the reaction type is not emoji.", "example": ":heart:", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the entity", "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "resource_id": { "description": "The unique identifier of the post this reaction was left on.", "type": "string" }, "user": { "description": "The user who left this reaction on the post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" } }, "required": [ "id", "resource_id", "user", "emoji" ], "type": "object" }, "ReactionListItem": { "description": "A single reaction left by a user on a feed post, such as a like or emoji.", "properties": { "emoji": { "description": "The emoji used for this reaction in shortcode format. Null if the reaction type is not emoji.", "example": ":heart:", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the entity", "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "resource_id": { "description": "The unique identifier of the post this reaction was left on.", "type": "string" }, "user": { "description": "The user who left this reaction on the post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" } }, "required": [ "id", "resource_id", "user", "emoji" ], "type": "object" }, "ReceiptStatus": { "description": "The status of a receipt", "enum": [ "draft", "open", "paid", "pending", "uncollectible", "unresolved", "void" ], "type": "string" }, "ReceiptTaxBehaviors": { "description": "The type of tax inclusivity applied to the receipt, for determining whether the tax is included in the final price, or paid on top.", "enum": [ "exclusive", "inclusive", "unspecified", "unable_to_collect" ], "type": "string" }, "ReceiptV2Order": { "description": "The order to sort the results by.", "enum": [ "final_amount", "created_at", "paid_at" ], "type": "string" }, "Refund": { "description": "A refund represents a full or partial reversal of a payment, including the amount, status, and payment provider.", "properties": { "amount": { "description": "The refunded amount as a decimal in the specified currency, such as 10.43 for $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the refund was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the refunded amount." }, "id": { "description": "The unique identifier for the refund.", "example": "rf_xxxxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The original payment that this refund was issued against. Null if the payment is no longer available.", "properties": { "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "The custom metadata stored on this payment. This will be copied over to the checkout configuration for which this payment was made", "type": [ "object", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "plan": { "description": "The plan attached to this payment.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": [ "object", "null" ] }, "product": { "description": "The product this payment was made for", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": [ "object", "null" ] }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "tax_amount": { "description": "The calculated amount of the sales/VAT tax (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "tax_behavior": { "description": "The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "tax_refunded_amount": { "description": "The amount of tax that has been refunded (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "total", "subtotal", "usd_total", "currency", "created_at", "paid_at", "dispute_alerted_at", "payment_method_type", "billing_reason", "card_brand", "card_last4", "tax_amount", "tax_behavior", "tax_refunded_amount", "metadata", "plan", "product", "user", "member", "membership" ], "type": [ "object", "null" ] }, "provider": { "$ref": "#/components/schemas/PaymentProviders", "description": "The payment provider that processed the refund." }, "provider_created_at": { "description": "The timestamp when the refund was created in the payment provider's system. Null if not available from the provider.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "reference_status": { "description": "The availability status of the refund tracking reference from the payment processor. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceStatuses" }, { "type": "null" } ] }, "reference_type": { "description": "The type of tracking reference provided by the payment processor, such as an acquirer reference number. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceTypes" }, { "type": "null" } ] }, "reference_value": { "description": "The tracking reference value from the payment processor, used to trace the refund through banking networks. Null if no reference was provided.", "example": "74850120752", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/RefundStatuses", "description": "The current processing status of the refund, such as pending, succeeded, or failed." } }, "required": [ "id", "amount", "currency", "status", "created_at", "provider", "provider_created_at", "reference_status", "reference_type", "reference_value", "payment" ], "type": "object" }, "RefundListItem": { "description": "A refund represents a full or partial reversal of a payment, including the amount, status, and payment provider.", "properties": { "amount": { "description": "The refunded amount as a decimal in the specified currency, such as 10.43 for $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the refund was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the refunded amount." }, "id": { "description": "The unique identifier for the refund.", "example": "rf_xxxxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The original payment that this refund was issued against. Null if the payment is no longer available.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "provider": { "$ref": "#/components/schemas/PaymentProviders", "description": "The payment provider that processed the refund." }, "provider_created_at": { "description": "The timestamp when the refund was created in the payment provider's system. Null if not available from the provider.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "reference_status": { "description": "The availability status of the refund tracking reference from the payment processor. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceStatuses" }, { "type": "null" } ] }, "reference_type": { "description": "The type of tracking reference provided by the payment processor, such as an acquirer reference number. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceTypes" }, { "type": "null" } ] }, "reference_value": { "description": "The tracking reference value from the payment processor, used to trace the refund through banking networks. Null if no reference was provided.", "example": "74850120752", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/RefundStatuses", "description": "The current processing status of the refund, such as pending, succeeded, or failed." } }, "required": [ "id", "amount", "currency", "status", "created_at", "provider", "provider_created_at", "reference_status", "reference_type", "reference_value", "payment" ], "type": "object" }, "RefundReferenceStatuses": { "description": "The status of the refund reference.", "enum": [ "available", "pending", "unavailable" ], "type": "string" }, "RefundReferenceTypes": { "description": "The type of refund reference that was made available by the payment provider.", "enum": [ "acquirer_reference_number", "retrieval_reference_number", "system_trace_audit_number" ], "type": "string" }, "RefundStatuses": { "description": "The different statuses for a Refund object", "enum": [ "pending", "requires_action", "succeeded", "failed", "canceled" ], "type": "string" }, "ReleaseMethod": { "description": "The methods of how a plan can be released.", "enum": [ "buy_now", "waitlist" ], "type": "string" }, "ResolutionCenterCase": { "description": "A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.", "properties": { "company": { "description": "The company involved in this resolution case. Null if the company no longer exists.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the resolution was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_appealed": { "description": "Whether the customer has filed an appeal after the initial resolution decision.", "type": "boolean" }, "customer_response_actions": { "description": "The list of actions currently available to the customer.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseCustomerResponses" }, "type": "array" }, "due_date": { "description": "The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution.", "example": "reso_xxxxxxxxxxxxx", "type": "string" }, "issue": { "$ref": "#/components/schemas/ResolutionCenterCaseIssueTypes", "description": "The category of the dispute." }, "member": { "description": "The membership record associated with the disputed payment. Null if the membership no longer exists.", "properties": { "id": { "description": "The unique identifier for the extra public member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "merchant_appealed": { "description": "Whether the merchant has filed an appeal after the initial resolution decision.", "type": "boolean" }, "merchant_response_actions": { "description": "The list of actions currently available to the merchant.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseMerchantResponses" }, "type": "array" }, "payment": { "description": "The payment record that is the subject of this resolution case.", "properties": { "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "subtotal": { "description": "The payment amount before taxes and discounts are applied. In the currency specified by the currency field.", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total amount charged to the customer for this payment, including taxes and after any discounts. In the currency specified by the currency field.", "example": 6.9, "type": "number" } }, "required": [ "id", "currency", "created_at", "paid_at", "total", "subtotal" ], "type": "object" }, "platform_response_actions": { "description": "The list of actions currently available to the Whop platform for moderating this resolution.", "items": { "$ref": "#/components/schemas/ResolutionCenterCasePlatformResponses" }, "type": "array" }, "resolution_events": { "description": "The most recent 50 messages, actions, and status changes that have occurred during this resolution case.", "items": { "description": "A resolution event is a message or action within a resolution case, such as a response, escalation, or status change.", "properties": { "action": { "$ref": "#/components/schemas/ResolutionCenterCaseActions", "description": "The type of action recorded in this event." }, "created_at": { "description": "The datetime the resolution event was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "details": { "description": "The message body or additional context provided with this resolution event. Null if no details were included.", "example": "I did not authorize this purchase.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution event.", "example": "revt_xxxxxxxxxxxxx", "type": "string" }, "reporter_type": { "$ref": "#/components/schemas/ResolutionCenterCaseReporters", "description": "The party who performed this action." } }, "required": [ "id", "action", "reporter_type", "details", "created_at" ], "type": "object" }, "type": "array" }, "status": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses", "description": "The current status of the resolution case, indicating which party needs to respond or if the case is closed." }, "updated_at": { "description": "The datetime the resolution was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The customer (buyer) who filed this resolution case.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "issue", "created_at", "updated_at", "due_date", "customer_appealed", "merchant_appealed", "customer_response_actions", "merchant_response_actions", "company", "user", "platform_response_actions", "payment", "member", "resolution_events" ], "type": "object" }, "ResolutionCenterCaseActions": { "description": "The different types of actions for a resolution event", "enum": [ "created", "responded", "accepted", "denied", "appealed", "withdrew", "requested_more_info", "escalated", "dispute_opened", "dispute_customer_won", "dispute_merchant_won" ], "type": "string" }, "ResolutionCenterCaseCustomerResponses": { "description": "The types of responses a customer can make to a resolution.", "enum": [ "respond", "appeal", "withdraw" ], "type": "string" }, "ResolutionCenterCaseIssueTypes": { "description": "The different types of issues a resolution can be", "enum": [ "forgot_to_cancel", "item_not_received", "significantly_not_as_described", "unauthorized_transaction", "product_unacceptable" ], "type": "string" }, "ResolutionCenterCaseListItem": { "description": "A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.", "properties": { "company": { "description": "The company involved in this resolution case. Null if the company no longer exists.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the resolution was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_appealed": { "description": "Whether the customer has filed an appeal after the initial resolution decision.", "type": "boolean" }, "customer_response_actions": { "description": "The list of actions currently available to the customer.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseCustomerResponses" }, "type": "array" }, "due_date": { "description": "The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution.", "example": "reso_xxxxxxxxxxxxx", "type": "string" }, "issue": { "$ref": "#/components/schemas/ResolutionCenterCaseIssueTypes", "description": "The category of the dispute." }, "merchant_appealed": { "description": "Whether the merchant has filed an appeal after the initial resolution decision.", "type": "boolean" }, "merchant_response_actions": { "description": "The list of actions currently available to the merchant.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseMerchantResponses" }, "type": "array" }, "payment": { "description": "The payment record that is the subject of this resolution case.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "status": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses", "description": "The current status of the resolution case, indicating which party needs to respond or if the case is closed." }, "updated_at": { "description": "The datetime the resolution was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The customer (buyer) who filed this resolution case.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "issue", "created_at", "updated_at", "due_date", "customer_appealed", "merchant_appealed", "customer_response_actions", "merchant_response_actions", "company", "user", "payment" ], "type": "object" }, "ResolutionCenterCaseMerchantResponses": { "description": "The types of responses a merchant can make to a resolution.", "enum": [ "accept", "deny", "request_more_info", "appeal", "respond" ], "type": "string" }, "ResolutionCenterCasePlatformResponses": { "description": "The types of responses the platform can make to a resolution.", "enum": [ "request_buyer_info", "request_merchant_info", "merchant_wins", "merchant_refund" ], "type": "string" }, "ResolutionCenterCaseReporters": { "description": "The different types of reporters for a resolution event", "enum": [ "merchant", "customer", "platform", "system" ], "type": "string" }, "ResolutionCenterCaseStatuses": { "description": "The statuses a resolution object can have", "enum": [ "merchant_response_needed", "customer_response_needed", "merchant_info_needed", "customer_info_needed", "under_platform_review", "customer_won", "merchant_won", "customer_withdrew" ], "type": "string" }, "ResultLabelKeys": { "description": "Types of optimization results tracked from external ad platforms", "enum": [ "app_installs", "messaging_conversations_started", "post_engagement", "event_responses", "impressions", "website_purchases", "landing_page_views", "leads", "link_clicks", "quality_calls", "appointments_booked", "messaging_purchases", "page_likes", "instagram_profile_visits", "reach", "reminders_set", "new_subscribers", "video_views", "registrations", "content_views", "searches", "website_schedules", "website_submit_applications", "custom" ], "type": "string" }, "Review": { "description": "A user-submitted review of a company, including a star rating and optional text feedback.", "properties": { "attachments": { "description": "A list of files and media attached to the review.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "company": { "description": "The company that this review was written for.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the review was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "The body text of the review containing the user's detailed feedback. Returns an empty string if no description was provided.", "example": "Great product, really helped me grow my audience.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the review.", "example": "rev_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "The timestamp of when the reviewer first joined the product. Null if unknown.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "paid_for_product": { "description": "Whether the reviewer paid for the product. Null if the payment status is unknown.", "type": [ "boolean", "null" ] }, "product": { "description": "The product that this review was written for.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "published_at": { "description": "The timestamp of when the review was published. Null if the review has not been published yet.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "stars": { "description": "The star rating given by the reviewer, from 1 to 5.", "example": 42, "type": "integer" }, "status": { "$ref": "#/components/schemas/ReviewStatus", "description": "The current moderation status of the review." }, "title": { "description": "A short summary title for the review. Null if the reviewer did not provide one.", "example": "Amazing community and tools", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the review was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user account of the person who wrote this review.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "title", "description", "stars", "status", "paid_for_product", "created_at", "updated_at", "published_at", "joined_at", "user", "attachments", "company", "product" ], "type": "object" }, "ReviewListItem": { "description": "A user-submitted review of a company, including a star rating and optional text feedback.", "properties": { "attachments": { "description": "A list of files and media attached to the review.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "created_at": { "description": "The datetime the review was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "The body text of the review containing the user's detailed feedback. Returns an empty string if no description was provided.", "example": "Great product, really helped me grow my audience.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the review.", "example": "rev_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "The timestamp of when the reviewer first joined the product. Null if unknown.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "paid_for_product": { "description": "Whether the reviewer paid for the product. Null if the payment status is unknown.", "type": [ "boolean", "null" ] }, "published_at": { "description": "The timestamp of when the review was published. Null if the review has not been published yet.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "stars": { "description": "The star rating given by the reviewer, from 1 to 5.", "example": 42, "type": "integer" }, "status": { "$ref": "#/components/schemas/ReviewStatus", "description": "The current moderation status of the review." }, "title": { "description": "A short summary title for the review. Null if the reviewer did not provide one.", "example": "Amazing community and tools", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the review was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user account of the person who wrote this review.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "title", "description", "stars", "status", "paid_for_product", "created_at", "updated_at", "published_at", "joined_at", "user", "attachments" ], "type": "object" }, "ReviewStatus": { "description": "The statuses a review can have", "enum": [ "pending", "published", "removed" ], "type": "string" }, "SetupIntent": { "description": "A setup intent allows a user to save a payment method for future use without making an immediate purchase.", "properties": { "checkout_configuration": { "description": "The checkout session configuration associated with this setup intent. Null if no checkout session was used.", "properties": { "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "company": { "description": "The company that initiated this setup intent. Null if the company has been deleted.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the setup intent was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "error_message": { "description": "A human-readable error message explaining why the setup intent failed. Null if no error occurred.", "example": "Your card was declined.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the setup intent.", "example": "sint_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member associated with this setup intent. Null if the user is not a member.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "user" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this setup intent. Null if no metadata was provided.", "type": [ "object", "null" ] }, "payment_method": { "description": "The saved payment method created by this setup intent. Null if the setup has not completed successfully.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "mailing_address": { "description": "The mailing address associated with the payment method's user", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card", "mailing_address" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/SetupIntentStatuses", "description": "The current status of the setup intent." } }, "required": [ "id", "status", "created_at", "error_message", "company", "checkout_configuration", "member", "payment_method", "metadata" ], "type": "object" }, "SetupIntentListItem": { "description": "A setup intent allows a user to save a payment method for future use without making an immediate purchase.", "properties": { "checkout_configuration": { "description": "The checkout session configuration associated with this setup intent. Null if no checkout session was used.", "properties": { "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "company": { "description": "The company that initiated this setup intent. Null if the company has been deleted.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the setup intent was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "error_message": { "description": "A human-readable error message explaining why the setup intent failed. Null if no error occurred.", "example": "Your card was declined.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the setup intent.", "example": "sint_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member associated with this setup intent. Null if the user is not a member.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "user" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this setup intent. Null if no metadata was provided.", "type": [ "object", "null" ] }, "payment_method": { "description": "The saved payment method created by this setup intent. Null if the setup has not completed successfully.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "mailing_address": { "description": "The mailing address associated with the payment method's user", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card", "mailing_address" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/SetupIntentStatuses", "description": "The current status of the setup intent." } }, "required": [ "id", "status", "created_at", "error_message", "company", "checkout_configuration", "member", "payment_method", "metadata" ], "type": "object" }, "SetupIntentStatuses": { "description": "The status of the setup intent.", "enum": [ "processing", "succeeded", "canceled", "requires_action" ], "type": "string" }, "Shipment": { "description": "A physical shipment associated with a payment, including carrier details and tracking information.", "properties": { "carrier": { "$ref": "#/components/schemas/ShipmentCarriers", "description": "The shipping carrier responsible for delivering this shipment." }, "created_at": { "description": "The datetime the shipment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "delivery_estimate": { "description": "The estimated delivery date for this shipment. Null if the carrier has not provided an estimate.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with this shipment. Null if the payment has been deleted or is inaccessible.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "service": { "description": "The shipping service level used for this shipment. Null if the carrier does not specify a service tier.", "example": "Priority", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "substatus": { "description": "A more granular status providing additional detail about the shipment's current state. Null if no substatus applies.", "oneOf": [ { "$ref": "#/components/schemas/ShipmentSubstatuses" }, { "type": "null" } ] }, "tracking_code": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "updated_at": { "description": "The datetime the shipment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "created_at", "status", "substatus", "tracking_code", "updated_at", "carrier", "service", "delivery_estimate", "payment" ], "type": "object" }, "ShipmentCarriers": { "description": "The carrier of a shipment", "enum": [ "accurate", "amazon_mws", "amazon_shipping", "apc", "asendia_usa", "australia_post", "axlehire_v3", "better_trucks", "canada_post", "canpar", "columbus_last_mile", "chronopost", "cloud_sort", "courier_express", "couriers_please", "cs_logistics", "dai_post", "deutsche_post_uk", "deutsche_post", "dhl_ecommerce_asia", "dhl_ecs", "dhl_express", "dhl_paket", "door_dash", "dpd_nl", "dpd_uk", "dpd", "epost_global", "estafeta", "evri", "fastway", "fedex_cross_border", "fedex_default", "fedex_mailview", "fedex_smartpost", "fedex", "first_choice", "first_mile", "flexport", "gio", "gio_express", "gso", "hailify", "henry", "interlink_express", "jet", "kuroneko_yamato", "la_post", "lasership_v2", "loomis_express", "lso", "ontrac", "optima", "osm_worldwide", "parcelforce", "parcll", "passport_global", "post_nl", "purolator", "quick", "royal_mail", "omni_parcel", "sendle", "sf_express", "smart_kargo", "sonic", "spee_dee", "swyft", "tforce", "uds", "ups_iparcel", "ups_mail_innovations", "ups", "usps", "veho", "yanwen" ], "type": "string" }, "ShipmentListItem": { "description": "A physical shipment associated with a payment, including carrier details and tracking information.", "properties": { "carrier": { "$ref": "#/components/schemas/ShipmentCarriers", "description": "The shipping carrier responsible for delivering this shipment." }, "created_at": { "description": "The datetime the shipment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "delivery_estimate": { "description": "The estimated delivery date for this shipment. Null if the carrier has not provided an estimate.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with this shipment. Null if the payment has been deleted or is inaccessible.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "service": { "description": "The shipping service level used for this shipment. Null if the carrier does not specify a service tier.", "example": "Priority", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "substatus": { "description": "A more granular status providing additional detail about the shipment's current state. Null if no substatus applies.", "oneOf": [ { "$ref": "#/components/schemas/ShipmentSubstatuses" }, { "type": "null" } ] }, "tracking_code": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "updated_at": { "description": "The datetime the shipment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "created_at", "status", "substatus", "tracking_code", "updated_at", "carrier", "service", "delivery_estimate", "payment" ], "type": "object" }, "ShipmentStatuses": { "description": "The status of a shipment", "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "type": "string" }, "ShipmentSubstatuses": { "description": "The substatus of a shipment", "enum": [ "address_correction", "arrived_at_destination", "arrived_at_facility", "arrived_at_pickup_location", "awaiting_information", "substatus_cancelled", "damaged", "delayed", "delivery_exception", "departed_facility", "departed_origin_facility", "expired", "substatus_failure", "held", "substatus_in_transit", "label_created", "lost", "missorted", "substatus_out_for_delivery", "received_at_destination_facility", "received_at_origin_facility", "refused", "return", "status_update", "transferred_to_destination_carrier", "transit_exception", "substatus_unknown", "weather_delay" ], "type": "string" }, "SocialLinkWebsites": { "description": "The different websites you can have social links for", "enum": [ "x", "instagram", "facebook", "tiktok", "youtube", "linkedin", "twitch", "website", "custom" ], "type": "string" }, "SpecificFeeOrigins": { "description": "The origin of the specific fee", "enum": [ "stripe_domestic_processing_fee", "stripe_international_processing_fee", "stripe_fixed_processing_fee", "stripe_billing_fee", "stripe_radar_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "stripe_sales_tax_fee", "whop_processing_fee", "marketplace_affiliate_fee", "affiliate_fee", "crypto_fee", "stripe_standard_processing_fee", "paypal_fee", "stripe_payout_fee", "dispute_fee", "dispute_alert_fee", "apple_processing_fee", "buyer_fee", "sezzle_processing_fee", "splitit_processing_fee", "platform_balance_processing_fee", "payment_processing_percentage_fee", "payment_processing_fixed_fee", "cross_border_percentage_fee", "fx_percentage_fee", "orchestration_percentage_fee", "three_ds_fixed_fee", "billing_percentage_fee", "revshare_percentage_fee", "application_fee" ], "type": "string" }, "Status": { "description": "Statuses for resources", "enum": [ "active", "archived", "deleted" ], "type": "string" }, "Statuses": { "description": "The available bounty statuses to choose from.", "enum": [ "published", "archived" ], "type": "string" }, "SupportChannel": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "company_id": { "description": "The unique identifier of the company associated with this channel. Null if this is not a support or company-scoped conversation.", "type": [ "string", "null" ] }, "custom_name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] }, "customer_user": { "description": "The customer who initiated this support conversation. Null if this is not a support chat.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "resolved_at": { "description": "The timestamp when the linked support ticket was marked as resolved. Null if unresolved or not a support chat.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "custom_name", "customer_user", "resolved_at", "last_message_at" ], "type": "object" }, "SupportChannelListItem": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "company_id": { "description": "The unique identifier of the company associated with this channel. Null if this is not a support or company-scoped conversation.", "type": [ "string", "null" ] }, "custom_name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] }, "customer_user": { "description": "The customer who initiated this support conversation. Null if this is not a support chat.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "resolved_at": { "description": "The timestamp when the linked support ticket was marked as resolved. Null if unresolved or not a support chat.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "custom_name", "customer_user", "resolved_at", "last_message_at" ], "type": "object" }, "SupportChannelView": { "description": "The perspective to filter support channels by.", "enum": [ "all", "admin", "customer" ], "type": "string" }, "TargetingDevicePlatforms": { "description": "Device platform targeting options.", "enum": [ "mobile", "desktop" ], "type": "string" }, "TargetingGenders": { "description": "Gender targeting options.", "enum": [ "male", "female", "all" ], "type": "string" }, "TargetingPlacementTypes": { "description": "Placement strategy for ad delivery.", "enum": [ "automatic", "manual" ], "type": "string" }, "TaxIdentifierTypes": { "description": "The type of tax identifier", "enum": [ "ad_nrt", "ao_tin", "ar_cuit", "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", "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", "pl_nip", "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", "xi_vat" ], "type": "string" }, "TaxTypes": { "description": "Whether or not the tax is included in a plan's price (or if it hasn't been set up)", "enum": [ "inclusive", "exclusive", "unspecified" ], "type": "string" }, "TiktokActionScene": { "description": "The category of TikTok content a behavioral targeting rule applies to. See docs/tiktok_api/ad_group.md § actions.", "enum": [ "VIDEO_RELATED", "CREATOR_RELATED", "HASHTAG_RELATED", "LIVE_RELATED" ], "type": "string" }, "TiktokAdGroupPlatformConfigAttributionEventCount": { "enum": [ "UNSET", "EVERY", "ONCE" ], "type": "string" }, "TiktokAdGroupPlatformConfigAudienceType": { "enum": [ "NORMAL", "SMART_INTERESTS_BEHAVIORS" ], "type": "string" }, "TiktokAdGroupPlatformConfigBidType": { "enum": [ "BID_TYPE_NO_BID", "BID_TYPE_CUSTOM" ], "type": "string" }, "TiktokAdGroupPlatformConfigBillingEvent": { "enum": [ "CPC", "CPM", "OCPM", "CPV" ], "type": "string" }, "TiktokAdGroupPlatformConfigBrandSafetyType": { "enum": [ "NO_BRAND_SAFETY", "STANDARD_INVENTORY", "LIMITED_INVENTORY", "FULL_INVENTORY", "EXPANDED_INVENTORY" ], "type": "string" }, "TiktokAdGroupPlatformConfigBudgetMode": { "enum": [ "BUDGET_MODE_DAY", "BUDGET_MODE_TOTAL", "BUDGET_MODE_DYNAMIC_DAILY_BUDGET" ], "type": "string" }, "TiktokAdGroupPlatformConfigClickAttributionWindow": { "enum": [ "OFF", "ONE_DAY", "SEVEN_DAYS", "FOURTEEN_DAYS", "TWENTY_EIGHT_DAYS" ], "type": "string" }, "TiktokAdGroupPlatformConfigDeepFunnelOptimizationStatus": { "enum": [ "ON", "OFF" ], "type": "string" }, "TiktokAdGroupPlatformConfigEngagedViewAttributionWindow": { "enum": [ "OFF", "ONE_DAY", "SEVEN_DAYS" ], "type": "string" }, "TiktokAdGroupPlatformConfigGender": { "enum": [ "GENDER_UNLIMITED", "GENDER_MALE", "GENDER_FEMALE" ], "type": "string" }, "TiktokAdGroupPlatformConfigIos14Targeting": { "enum": [ "UNSET", "IOS14_MINUS", "IOS14_PLUS", "ALL" ], "type": "string" }, "TiktokAdGroupPlatformConfigOperationStatus": { "enum": [ "ENABLE", "DISABLE" ], "type": "string" }, "TiktokAdGroupPlatformConfigOptimizationGoal": { "enum": [ "CLICK", "CONVERT", "INSTALL", "IN_APP_EVENT", "REACH", "SHOW", "VIDEO_VIEW", "ENGAGED_VIEW", "ENGAGED_VIEW_FIFTEEN", "LEAD_GENERATION", "PREFERRED_LEAD", "CONVERSATION", "FOLLOWERS", "PROFILE_VIEWS", "PAGE_VISIT", "VALUE", "AUTOMATIC_VALUE_OPTIMIZATION", "TRAFFIC_LANDING_PAGE_VIEW", "DESTINATION_VISIT", "MT_LIVE_ROOM", "PRODUCT_CLICK_IN_LIVE" ], "type": "string" }, "TiktokAdGroupPlatformConfigPacing": { "enum": [ "PACING_MODE_SMOOTH", "PACING_MODE_FAST" ], "type": "string" }, "TiktokAdGroupPlatformConfigPlacementType": { "enum": [ "PLACEMENT_TYPE_AUTOMATIC", "PLACEMENT_TYPE_NORMAL" ], "type": "string" }, "TiktokAdGroupPlatformConfigProductSource": { "enum": [ "CATALOG", "STORE", "SHOWCASE" ], "type": "string" }, "TiktokAdGroupPlatformConfigScheduleType": { "enum": [ "SCHEDULE_START_END", "SCHEDULE_FROM_NOW" ], "type": "string" }, "TiktokAdGroupPlatformConfigShoppingAdsRetargetingType": { "enum": [ "OFF", "LAB1", "LAB2", "LAB3", "LAB4", "LAB5" ], "type": "string" }, "TiktokAdGroupPlatformConfigSpendingPower": { "enum": [ "ALL", "HIGH" ], "type": "string" }, "TiktokAdGroupPlatformConfigViewAttributionWindow": { "enum": [ "OFF", "ONE_DAY", "SEVEN_DAYS" ], "type": "string" }, "TiktokAgeGroup": { "description": "Age groups targetable on TikTok. See docs/tiktok_api/ad_group.md § age_groups.", "enum": [ "AGE_13_17", "AGE_18_24", "AGE_25_34", "AGE_35_44", "AGE_45_54", "AGE_55_100" ], "type": "string" }, "TiktokOperatingSystem": { "description": "Device operating systems targetable on TikTok. See docs/tiktok_api/ad_group.md § operating_systems.", "enum": [ "ANDROID", "IOS" ], "type": "string" }, "TiktokVideoUserAction": { "description": "Specific past video interactions used for behavioral targeting. See docs/tiktok_api/ad_group.md § actions.video_user_actions.", "enum": [ "WATCHED_TO_END", "LIKED", "COMMENTED", "SHARED", "FOLLOWED", "PROFILE_VISITED" ], "type": "string" }, "Topup": { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "failure_message": { "description": "If the payment failed, the reason for the failure.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').", "oneOf": [ { "$ref": "#/components/schemas/ReceiptStatus" }, { "type": "null" } ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "id", "status", "created_at", "paid_at", "currency", "total", "failure_message" ], "type": "object" }, "Transfer": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "The transfer amount in the currency specified by the currency field. For example, 10.43 represents $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the credit transaction transfer was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency in which this transfer amount is denominated." }, "destination": { "description": "The entity receiving the transferred funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A user account on Whop. Contains profile information, identity details, and social connections.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "typename": { "const": "User", "description": "The typename of this object", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "typename", "id", "name", "username" ], "title": "User", "type": [ "object", "null" ] }, { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" }, "typename": { "const": "Company", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "route", "title" ], "title": "Company", "type": [ "object", "null" ] } ], "type": "object" }, "destination_ledger_account_id": { "description": "The unique identifier of the ledger account receiving the funds.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" }, "fee_amount": { "description": "The flat fee amount deducted from this transfer, in the transfer's currency. Null if no flat fee was applied.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for the credit transaction transfer.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this transfer. Maximum 50 keys, 500 characters per key, 5000 characters per value.", "type": [ "object", "null" ] }, "notes": { "description": "A free-text note attached to this transfer by the sender. Null if no note was provided.", "example": "Monthly revenue share payout", "type": [ "string", "null" ] }, "origin": { "description": "The entity that sent the transferred funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A user account on Whop. Contains profile information, identity details, and social connections.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "typename": { "const": "User", "description": "The typename of this object", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "typename", "id", "name", "username" ], "title": "User", "type": [ "object", "null" ] }, { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The URL slug for the company's store page (e.g., 'pickaxe' in whop.com/pickaxe).", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" }, "typename": { "const": "Company", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "route", "title" ], "title": "Company", "type": [ "object", "null" ] } ], "type": "object" }, "origin_ledger_account_id": { "description": "The unique identifier of the ledger account that sent the funds.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "amount", "currency", "created_at", "fee_amount", "notes", "metadata", "origin_ledger_account_id", "destination_ledger_account_id", "origin", "destination" ], "type": "object" }, "TransferListItem": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "The transfer amount in the currency specified by the currency field. For example, 10.43 represents $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the credit transaction transfer was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency in which this transfer amount is denominated." }, "destination_ledger_account_id": { "description": "The unique identifier of the ledger account receiving the funds.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" }, "fee_amount": { "description": "The flat fee amount deducted from this transfer, in the transfer's currency. Null if no flat fee was applied.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for the credit transaction transfer.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this transfer. Maximum 50 keys, 500 characters per key, 5000 characters per value.", "type": [ "object", "null" ] }, "notes": { "description": "A free-text note attached to this transfer by the sender. Null if no note was provided.", "example": "Monthly revenue share payout", "type": [ "string", "null" ] }, "origin_ledger_account_id": { "description": "The unique identifier of the ledger account that sent the funds.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "amount", "currency", "created_at", "fee_amount", "notes", "metadata", "origin_ledger_account_id", "destination_ledger_account_id" ], "type": "object" }, "UploadStatuses": { "description": "The upload status of a file", "enum": [ "pending", "processing", "ready", "failed" ], "type": "string" }, "User": { "properties": { "bio": { "description": "The user's biography", "nullable": true, "type": "string" }, "created_at": { "description": "When the user was created, as an ISO 8601 timestamp", "type": "string" }, "id": { "description": "The ID of the user, which will look like user_*************", "type": "string" }, "name": { "description": "The user's display name", "nullable": true, "type": "string" }, "profile_picture": { "description": "The user's profile picture, an object with a url", "nullable": true, "type": "object" }, "username": { "description": "The user's unique username", "type": "string" } }, "required": [ "id", "username", "name", "bio", "created_at", "profile_picture" ], "type": "object" }, "V1ErrorResponse": { "properties": { "error": { "properties": { "message": { "description": "Human-readable error message.", "type": "string" }, "type": { "description": "Machine-readable error code.", "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Verification": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": "object" }, "VerificationErrorCodes": { "description": "An error code for a verification attempt.", "enum": [ "abandoned", "consent_declined", "country_not_supported", "device_not_supported", "document_expired", "document_type_not_supported", "document_unverified_other", "email_unverified_other", "email_verification_declined", "id_number_insufficient_document_data", "id_number_mismatch", "id_number_unverified_other", "phone_unverified_other", "phone_verification_declined", "selfie_document_missing_photo", "selfie_face_mismatch", "selfie_manipulated", "selfie_unverified_other", "under_supported_age" ], "type": "string" }, "VerificationListItem": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": "object" }, "VerificationStatuses": { "description": "A status for a verification.", "enum": [ "requires_input", "processing", "verified", "canceled", "created", "started", "submitted", "approved", "declined", "resubmission_requested", "expired", "abandoned", "review", "action_required" ], "type": "string" }, "Visibility": { "description": "Visibility of a resource", "enum": [ "visible", "hidden", "archived", "quick_link" ], "type": "string" }, "VisibilityFilter": { "description": "The different levels of visibility for resources", "enum": [ "visible", "hidden", "archived", "quick_link", "all", "not_quick_link", "not_archived" ], "type": "string" }, "Webhook": { "description": "A webhook endpoint that receives event notifications for a company via HTTP POST.", "properties": { "api_version": { "$ref": "#/components/schemas/ApiVersion", "description": "The API version used to format payloads sent to this webhook endpoint." }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on a company, enabling this sends events only from the company's sub-merchants (child companies).", "type": "boolean" }, "created_at": { "description": "The datetime the webhook was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "type": "boolean" }, "events": { "description": "The list of event types this webhook is subscribed to.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "id": { "description": "The unique identifier for the webhook.", "example": "hook_xxxxxxxxxxxxx", "type": "string" }, "resource_id": { "description": "The ID of the resource (company or product) this webhook is attached to.", "type": "string" }, "testable_events": { "description": "The subset of subscribed event types that support sending test payloads.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "url": { "description": "The destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/path", "type": "string" } }, "required": [ "id", "url", "enabled", "events", "api_version", "created_at", "child_resource_events", "testable_events", "resource_id" ], "type": "object" }, "WebhookEvent": { "description": "The different event types available", "enum": [ "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "withdrawal.created", "withdrawal.updated", "course_lesson_interaction.completed", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed" ], "type": "string" }, "WebhookListItem": { "description": "A webhook endpoint that receives event notifications for a company via HTTP POST.", "properties": { "api_version": { "$ref": "#/components/schemas/ApiVersion", "description": "The API version used to format payloads sent to this webhook endpoint." }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on a company, enabling this sends events only from the company's sub-merchants (child companies).", "type": "boolean" }, "created_at": { "description": "The datetime the webhook was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "type": "boolean" }, "events": { "description": "The list of event types this webhook is subscribed to.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "id": { "description": "The unique identifier for the webhook.", "example": "hook_xxxxxxxxxxxxx", "type": "string" }, "url": { "description": "The destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/path", "type": "string" } }, "required": [ "id", "url", "enabled", "events", "api_version", "created_at", "child_resource_events" ], "type": "object" }, "WhoCanPostTypes": { "description": "Who can post on a chat feed", "enum": [ "everyone", "admins" ], "type": "string" }, "WhoCanReactTypes": { "description": "Who can react on a chat feed", "enum": [ "everyone", "no_one" ], "type": "string" }, "Withdrawal": { "description": "A withdrawal represents a request to transfer funds from a ledger account to an external payout method.", "properties": { "amount": { "description": "The withdrawal amount as a decimal number in the specified currency (e.g., 100.00 for $100.00 USD).", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the withdrawal was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this withdrawal (e.g., 'usd', 'eur')." }, "error_code": { "description": "A machine-readable error code describing why the payout failed. Null if no error occurred.", "oneOf": [ { "$ref": "#/components/schemas/PayoutErrorCodes" }, { "type": "null" } ] }, "error_message": { "description": "A human-readable message describing why the payout failed. Null if no error occurred.", "example": "Destination bank account is invalid.", "type": [ "string", "null" ] }, "estimated_availability": { "description": "The estimated time at which the funds become available in the destination account. Null if no estimate is available. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "fee_amount": { "description": "The fee charged for processing this withdrawal, in the same currency as the withdrawal amount.", "example": 6.9, "type": "number" }, "fee_type": { "description": "How the fee was applied to the withdrawal. 'exclusive' means the fee was added on top (user receives the full requested amount). 'inclusive' means the fee was deducted from the withdrawal (user receives less than requested). Null if no fee was charged.", "oneOf": [ { "$ref": "#/components/schemas/WithdrawalFeeTypes" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the withdrawal.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "ledger_account": { "description": "The ledger account from which the withdrawal funds are sourced.", "properties": { "company_id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the ledger account.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "company_id" ], "type": "object" }, "markup_fee": { "description": "An additional markup fee charged for the withdrawal, in the same currency as the withdrawal amount. Only applies to platform accounts using Whop Rails.", "example": 6.9, "type": "number" }, "payout_token": { "description": "The saved payout destination used for this withdrawal (e.g., a bank account or PayPal address). Null if no payout token was used.", "properties": { "created_at": { "description": "The datetime the payout token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "destination_currency_code": { "description": "The three-letter ISO currency code that payouts are delivered in for this destination.", "example": "USD", "type": "string" }, "id": { "description": "The unique identifier for the payout token.", "example": "potk_xxxxxxxxxxxxx", "type": "string" }, "nickname": { "description": "A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.", "example": "My Business Account", "type": [ "string", "null" ] }, "payer_name": { "description": "The legal name of the account holder receiving payouts. Null if not provided.", "example": "Acme Corp LLC", "type": [ "string", "null" ] } }, "required": [ "id", "payer_name", "nickname", "destination_currency_code", "created_at" ], "type": [ "object", "null" ] }, "speed": { "$ref": "#/components/schemas/WithdrawalSpeeds", "description": "The processing speed selected for this withdrawal ('standard' or 'instant')." }, "status": { "$ref": "#/components/schemas/WithdrawalStatus", "description": "The computed lifecycle status of the withdrawal, accounting for the state of associated payouts (e.g., 'requested', 'in_transit', 'completed', 'failed')." }, "trace_code": { "description": "The ACH trace number for tracking the payout through the banking network. Null if not available or not an ACH transaction.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "id", "status", "amount", "currency", "fee_amount", "fee_type", "speed", "created_at", "markup_fee", "ledger_account", "payout_token", "error_code", "error_message", "estimated_availability", "trace_code" ], "type": "object" }, "WithdrawalFeeTypes": { "description": "The different fee types for a withdrawal.", "enum": [ "exclusive", "inclusive" ], "type": "string" }, "WithdrawalListItem": { "description": "A withdrawal represents a request to transfer funds from a ledger account to an external payout method.", "properties": { "amount": { "description": "The withdrawal amount as a decimal number in the specified currency (e.g., 100.00 for $100.00 USD).", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the withdrawal was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this withdrawal (e.g., 'usd', 'eur')." }, "fee_amount": { "description": "The fee charged for processing this withdrawal, in the same currency as the withdrawal amount.", "example": 6.9, "type": "number" }, "fee_type": { "description": "How the fee was applied to the withdrawal. 'exclusive' means the fee was added on top (user receives the full requested amount). 'inclusive' means the fee was deducted from the withdrawal (user receives less than requested). Null if no fee was charged.", "oneOf": [ { "$ref": "#/components/schemas/WithdrawalFeeTypes" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the withdrawal.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "An additional markup fee charged for the withdrawal, in the same currency as the withdrawal amount. Only applies to platform accounts using Whop Rails.", "example": 6.9, "type": "number" }, "speed": { "$ref": "#/components/schemas/WithdrawalSpeeds", "description": "The processing speed selected for this withdrawal ('standard' or 'instant')." }, "status": { "$ref": "#/components/schemas/WithdrawalStatus", "description": "The computed lifecycle status of the withdrawal, accounting for the state of associated payouts (e.g., 'requested', 'in_transit', 'completed', 'failed')." } }, "required": [ "id", "status", "amount", "currency", "fee_amount", "fee_type", "speed", "created_at", "markup_fee" ], "type": "object" }, "WithdrawalSpeeds": { "description": "The different speeds of withdrawals", "enum": [ "standard", "instant" ], "type": "string" }, "WithdrawalStatus": { "description": "The status of a withdrawal request", "enum": [ "requested", "awaiting_payment", "in_transit", "completed", "failed", "canceled", "denied" ], "type": "string" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "auth-scheme", "description": "A company API key, company scoped JWT, app API key, or user OAuth token. You must prepend your key/token with the word 'Bearer', which will look like `Bearer ***************************`", "scheme": "bearer", "type": "http" } } }, "info": { "description": "The Whop REST API. Please see https://docs.whop.com/developer/api/getting-started for more details.", "termsOfService": "https://whop.com/tos-developer-api/", "title": "Whop API", "version": "1.0.0", "x-api-version-date": "2026-06-09" }, "openapi": "3.1.0", "paths": { "/access_tokens": { "post": { "description": "Create a short-lived access token for authenticating API requests. When using API key authentication, provide company_id or user_id. When using OAuth, the user is derived from the token. Use this token with Whop's web and mobile embedded components.", "operationId": "createAccessToken", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAccessToken", "properties": { "company_id": { "description": "The unique identifier of the company to generate the token for, starting with 'biz_'. The API key must have permission to access this company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "expires_at": { "description": "The expiration timestamp for the access token. Defaults to 1 hour from now, with a maximum of 3 hours.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "scoped_actions": { "description": "An array of permission scopes to grant to the access token. If empty or omitted, all permissions from the authenticating credential are inherited. Must be a subset of the credential's permissions.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "user_id": { "description": "The unique identifier of the user to generate the token for, starting with 'user_'. The API key must have permission to access this user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create access token", "tags": [ "Access tokens" ], "x-group-title": "Developer" } }, "/account_links": { "post": { "description": "Generate a URL that directs a sub-merchant to their account portal, such as the hosted payouts dashboard or the KYC onboarding flow.", "operationId": "createAccountLink", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAccountLink", "properties": { "company_id": { "description": "The unique identifier of the company to generate the link for, starting with 'biz_'. Must be a sub-merchant of the API key's company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "refresh_url": { "description": "The URL to redirect the user to if the session expires and needs to be re-authenticated, such as 'https://example.com/refresh'.", "type": "string" }, "return_url": { "description": "The URL to redirect the user to when they want to return to your site, such as 'https://example.com/return'.", "type": "string" }, "use_case": { "$ref": "#/components/schemas/AccountLinkUseCases", "description": "The purpose of the account link, such as hosted payouts portal or hosted KYC onboarding." } }, "required": [ "company_id", "refresh_url", "return_url", "use_case" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLink" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create account link", "tags": [ "Account links" ], "x-group-title": "Developer" } }, "/accounts": { "get": { "description": "Lists accounts visible to the credential. User tokens return the user's business accounts; business account API keys return the requesting business account and its connected accounts.", "operationId": "listAccounts", "parameters": [ { "description": "The page number to retrieve", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "type": "integer" } }, { "description": "The number of resources to return per page. There is a limit of 50 results per page.", "in": "query", "name": "per", "required": false, "schema": { "default": 10, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/Account" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "pagination", "accounts" ], "type": "object" } } }, "description": "accounts listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Accounts", "tags": [ "Accounts" ] }, "post": { "description": "Creates an account. User tokens create business accounts; business account API keys create connected accounts.", "operationId": "createAccount", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "The email address of the account owner. Required for business account API key requests.", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key/value metadata to store on the account.", "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required connected-account creation scope" } }, "security": [ { "bearerAuth": [ "company:create_child" ] } ], "summary": "Create Account", "tags": [ "Accounts" ] } }, "/accounts/me": { "get": { "description": "Retrieves the business account associated with the current business account API key.", "operationId": "retrieveRequestingAccount", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "requesting account retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Retrieve Requesting Account", "tags": [ "Accounts" ] } }, "/accounts/{account_id}": { "get": { "description": "Retrieves a single account visible to the credential, including its crypto wallet.", "operationId": "retrieveAccount", "parameters": [ { "description": "The ID of the account, which will look like biz_*************", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Retrieve Account", "tags": [ "Accounts" ] }, "patch": { "description": "Updates an account. User tokens can update business accounts; business account API keys can update connected accounts.", "operationId": "updateAccount", "parameters": [ { "description": "The ID of the account, which will look like biz_*************", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "affiliate_application_required": { "description": "Whether prospective affiliates must submit an application before promoting this account.", "type": "boolean" }, "affiliate_instructions": { "description": "Guidelines shown to affiliates promoting this account.", "nullable": true, "type": "string" }, "banner_image": { "additionalProperties": true, "description": "Attachment input for the account banner image.", "nullable": true, "type": "object" }, "business_type": { "description": "The high-level business category for the account.", "nullable": true, "type": "string" }, "country": { "description": "The country the account is located in.", "nullable": true, "type": "string" }, "description": { "description": "A promotional description for the account.", "nullable": true, "type": "string" }, "featured_affiliate_product_id": { "description": "The ID of the product to feature for affiliates. Pass null to clear.", "nullable": true, "type": "string" }, "home_preferences": { "description": "Preferences for the public business home page.", "items": { "type": "string" }, "type": "array" }, "industry_group": { "description": "The industry group the account belongs to.", "nullable": true, "type": "string" }, "industry_type": { "description": "The specific industry vertical the account operates in.", "nullable": true, "type": "string" }, "invoice_prefix": { "description": "The prefix to use for account invoices.", "nullable": true, "type": "string" }, "logo": { "additionalProperties": true, "description": "Attachment input for the account logo.", "nullable": true, "type": "object" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key/value metadata to store on the account.", "type": "object" }, "onboarding_type": { "description": "The type of onboarding the account has completed.", "nullable": true, "type": "string" }, "opengraph_image": { "additionalProperties": true, "description": "Attachment input for the account Open Graph image.", "nullable": true, "type": "object" }, "opengraph_image_variant": { "description": "The account Open Graph image variant.", "nullable": true, "type": "string" }, "other_business_description": { "description": "The description of the business type when business_type is other.", "nullable": true, "type": "string" }, "other_industry_description": { "description": "The description of the industry type when industry_type is other.", "nullable": true, "type": "string" }, "require_2fa": { "description": "Whether the account requires authorized users to have two-factor authentication enabled.", "type": "boolean" }, "route": { "description": "The unique URL slug for the account.", "nullable": true, "type": "string" }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this account.", "type": "boolean" }, "show_joined_whops": { "description": "Whether the account appears in joined whops on other accounts.", "type": "boolean" }, "show_reviews_dtc": { "description": "Whether reviews are displayed on direct-to-consumer product pages.", "type": "boolean" }, "show_user_directory": { "description": "Whether the account shows users in the user directory.", "type": "boolean" }, "social_links": { "description": "The full list of social links to display for the account.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "store_page_config": { "additionalProperties": true, "description": "Store page display configuration for the account.", "nullable": true, "type": "object" }, "target_audience": { "description": "The target audience for this account.", "nullable": true, "type": "string" }, "title": { "description": "The display name of the account.", "nullable": true, "type": "string" }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image.", "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "store page config is not an object" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "company:update" ] } ], "summary": "Update Account", "tags": [ "Accounts" ] } }, "/ad_campaigns": { "get": { "description": "Returns a paginated list of ad campaigns for a company, with optional filtering by status, and creation date.\n\nRequired permissions:\n - `ad_campaign:basic:read`", "operationId": "listAdCampaign", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list ad campaigns for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter ad campaigns by their current status.", "oneOf": [ { "$ref": "#/components/schemas/AdCampaignStatuses" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return ad campaigns created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return ad campaigns created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Case-insensitive substring match against the campaign title or ID.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_from", "required": false, "schema": { "description": "Inclusive start of the window for each campaign's metric fields (spend, impressions, …). Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_to", "required": false, "schema": { "description": "Inclusive end of the window for each campaign's metric fields. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AdCampaign.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AdCampaignListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List ad campaigns", "tags": [ "Ad campaigns" ], "x-group-title": "Ads" } }, "/ad_campaigns/{id}": { "get": { "description": "Retrieves a single ad campaign by its unique identifier.\n\nRequired permissions:\n - `ad_campaign:basic:read`", "operationId": "retrieveAdCampaign", "parameters": [ { "description": "The unique identifier of the ad campaign.", "in": "path", "name": "id", "required": true, "schema": { "example": "adcamp_xxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "stats_from", "required": false, "schema": { "description": "Inclusive start of the window for the campaign's metric fields (spend, impressions, …). Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_to", "required": false, "schema": { "description": "Inclusive end of the window for the campaign's metric fields. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve ad campaign", "tags": [ "Ad campaigns" ], "x-group-title": "Ads" }, "patch": { "description": "Updates an ad campaign synchronously.\n\nRequired permissions:\n - `ad_campaign:update`", "operationId": "updateAdCampaign", "parameters": [ { "description": "The unique identifier of the ad campaign to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "adcamp_xxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAdCampaignV2", "properties": { "budget": { "description": "The campaign budget in dollars. The interpretation (daily or lifetime) follows the campaign's existing budget type.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update ad campaign", "tags": [ "Ad campaigns" ], "x-group-title": "Ads" } }, "/ad_campaigns/{id}/pause": { "post": { "description": "Pauses an ad campaign, optionally until a specific date.\n\nRequired permissions:\n - `ad_campaign:update`", "operationId": "pauseAdCampaign", "parameters": [ { "description": "The unique identifier of the ad campaign to pause.", "in": "path", "name": "id", "required": true, "schema": { "example": "adcamp_xxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause ad campaign", "tags": [ "Ad campaigns" ], "x-group-title": "Ads" } }, "/ad_campaigns/{id}/unpause": { "post": { "description": "Resumes a paused ad campaign.\n\nRequired permissions:\n - `ad_campaign:update`", "operationId": "unpauseAdCampaign", "parameters": [ { "description": "The unique identifier of the ad campaign to unpause.", "in": "path", "name": "id", "required": true, "schema": { "example": "adcamp_xxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause ad campaign", "tags": [ "Ad campaigns" ], "x-group-title": "Ads" } }, "/ad_groups": { "get": { "description": "Returns a paginated list of ad groups scoped by campaign or company, with optional filtering by status and creation date.\n\nRequired permissions:\n - `ad_campaign:basic:read`", "operationId": "listAdGroup", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "description": "Only return ad groups belonging to these ad campaigns (max 100). Can be combined with companyId or used on its own.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Filter by company. Provide companyId or adCampaignIds.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return ad groups created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return ad groups created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Case-insensitive substring match against the ad group name or ID.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_from", "required": false, "schema": { "description": "Inclusive start of the window for each ad group's metric fields (spend, impressions, …). Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_to", "required": false, "schema": { "description": "Inclusive end of the window for each ad group's metric fields. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter ad groups by their current status.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupStatuses" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "campaign_id", "required": false, "schema": { "description": "Filter by campaign.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_campaign_id", "required": false, "schema": { "description": "Filter by ad campaign. Provide exactly one of ad_campaign_id or company_id.", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ExternalAdGroup.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AdGroupListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List ad groups", "tags": [ "Ad groups" ], "x-group-title": "Ads" } }, "/ad_groups/{id}": { "delete": { "description": "Soft-deletes an ad group.\n\nRequired permissions:\n - `ad_campaign:update`", "operationId": "deleteAdGroup", "parameters": [ { "description": "The unique identifier of the ad group to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "adgrp_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete ad group", "tags": [ "Ad groups" ], "x-group-title": "Ads" }, "get": { "description": "Retrieves a single ad group by its unique identifier.\n\nRequired permissions:\n - `ad_campaign:basic:read`", "operationId": "retrieveAdGroup", "parameters": [ { "description": "The unique identifier of the ad group.", "in": "path", "name": "id", "required": true, "schema": { "example": "adgrp_xxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "stats_from", "required": false, "schema": { "description": "Inclusive start of the window for the ad group's metric fields (spend, impressions, …). Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_to", "required": false, "schema": { "description": "Inclusive end of the window for the ad group's metric fields. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve ad group", "tags": [ "Ad groups" ], "x-group-title": "Ads" }, "patch": { "description": "Updates an existing ad group.\n\nRequired permissions:\n - `ad_campaign:update`\n - `ad_campaign:basic:read`", "operationId": "updateAdGroup", "parameters": [ { "description": "The unique identifier of the ad group to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "adgrp_xxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAdGroupV2", "properties": { "budget": { "description": "Budget amount in dollars.", "example": 6.9, "type": [ "number", "null" ] }, "budget_type": { "description": "Whether the budget is daily or lifetime.", "oneOf": [ { "$ref": "#/components/schemas/AdBudgetTypes" }, { "type": "null" } ] }, "config": { "description": "Unified ad group configuration (bidding, optimization, targeting).", "properties": { "bid_amount": { "description": "Bid cap amount in cents. Used when bid_strategy is bid_cap or cost_cap.", "example": 42, "type": [ "integer", "null" ] }, "bid_strategy": { "description": "Bid strategy: lowest_cost, bid_cap, or cost_cap.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupConfigBidStrategy" }, { "type": "null" } ] }, "billing_event": { "description": "How you are billed (e.g., impressions, clicks).", "oneOf": [ { "$ref": "#/components/schemas/AdGroupConfigBillingEvent" }, { "type": "null" } ] }, "end_time": { "description": "Scheduled end time (ISO8601). Required for lifetime budgets.", "type": [ "string", "null" ] }, "frequency_cap": { "description": "Maximum number of times to show ads to each person in the frequency interval.", "example": 42, "type": [ "integer", "null" ] }, "frequency_cap_interval_days": { "description": "Number of days for the frequency cap interval.", "example": 42, "type": [ "integer", "null" ] }, "optimization_goal": { "description": "What the ad group optimizes for (e.g., conversions, link_clicks, reach).", "oneOf": [ { "$ref": "#/components/schemas/AdGroupConfigOptimizationGoal" }, { "type": "null" } ] }, "pacing": { "description": "Budget pacing: standard (even) or accelerated (fast).", "oneOf": [ { "$ref": "#/components/schemas/AdGroupConfigPacing" }, { "type": "null" } ] }, "start_time": { "description": "Scheduled start time (ISO8601).", "type": [ "string", "null" ] }, "targeting": { "description": "Audience targeting settings (demographics, geo, interests, audiences, devices).", "properties": { "age_max": { "description": "Maximum age for demographic targeting.", "example": 42, "type": [ "integer", "null" ] }, "age_min": { "description": "Minimum age for demographic targeting.", "example": 42, "type": [ "integer", "null" ] }, "countries": { "description": "ISO 3166-1 alpha-2 country codes to target.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "device_platforms": { "description": "Device platforms to target.", "items": { "$ref": "#/components/schemas/TargetingDevicePlatforms" }, "type": [ "array", "null" ] }, "exclude_audience_ids": { "description": "Platform audience IDs to exclude.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "genders": { "description": "Genders to target.", "items": { "$ref": "#/components/schemas/TargetingGenders" }, "type": [ "array", "null" ] }, "include_audience_ids": { "description": "Platform audience IDs to include.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "interest_ids": { "description": "Platform-specific interest IDs to target.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "languages": { "description": "Language codes to target.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "placement_type": { "description": "Placement strategy.", "oneOf": [ { "$ref": "#/components/schemas/TargetingPlacementTypes" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "daily_budget": { "description": "Daily budget in dollars.", "example": 6.9, "type": [ "number", "null" ] }, "name": { "description": "Human-readable ad group name.", "type": [ "string", "null" ] }, "platform_config": { "description": "Platform-specific ad group configuration.", "properties": { "meta": { "description": "Meta (Facebook/Instagram) ad set configuration.", "properties": { "android_devices": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "attribution_setting": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "attribution_spec": { "description": "Conversion attribution windows.", "items": { "description": "Meta conversion attribution window.", "properties": { "event_type": { "description": "Attribution event type (e.g., CLICK_THROUGH, VIEW_THROUGH).", "type": "string" }, "window_days": { "description": "Attribution window in days (1, 7, 28).", "example": 42, "type": "integer" } }, "required": [ "event_type", "window_days" ], "type": "object" }, "type": [ "array", "null" ] }, "audience_network_positions": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "audience_type": { "description": "Audience type for retargeting.", "type": [ "string", "null" ] }, "bid_amount": { "description": "Bid amount in cents.", "example": 42, "type": [ "integer", "null" ] }, "bid_strategy": { "description": "Meta bid strategy.", "oneOf": [ { "$ref": "#/components/schemas/MetaAdGroupPlatformConfigBidStrategy" }, { "type": "null" } ] }, "billing_event": { "description": "How you are billed on Meta.", "oneOf": [ { "$ref": "#/components/schemas/MetaAdGroupPlatformConfigBillingEvent" }, { "type": "null" } ] }, "brand_safety_content_filter_levels": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "budget_remaining": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "cost_per_result_goal": { "description": "Represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).", "example": 6.9, "type": [ "number", "null" ] }, "created_time": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "daily_budget": { "description": "Daily budget in cents.", "example": 42, "type": [ "integer", "null" ] }, "daily_min_spend_target": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "daily_spend_cap": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "destination_type": { "description": "Where ads in this ad set direct people.", "oneOf": [ { "$ref": "#/components/schemas/MetaAdGroupPlatformConfigDestinationType" }, { "type": "null" } ] }, "dsa_beneficiary": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "dsa_payor": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "end_time": { "description": "End time (ISO8601). Required for lifetime budgets.", "type": [ "string", "null" ] }, "excluded_geo_locations": { "description": "Geo locations to exclude.", "properties": { "cities": { "description": "City targets.", "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] }, "countries": { "description": "ISO 3166-1 alpha-2 country codes.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "location_types": { "description": "Location types (home, recent, travel_in).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "regions": { "description": "Region/state targets.", "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] }, "zips": { "description": "Zip/postal code targets.", "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "facebook_positions": { "description": "Facebook ad placements (feed, reels, stories, etc.).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "frequency_control_count": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": [ "integer", "null" ] }, "frequency_control_days": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": [ "integer", "null" ] }, "frequency_control_type": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "geo_cities": { "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] }, "geo_locations": { "description": "Geo targeting (countries, regions, cities, zips).", "properties": { "cities": { "description": "City targets.", "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] }, "countries": { "description": "ISO 3166-1 alpha-2 country codes.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "location_types": { "description": "Location types (home, recent, travel_in).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "regions": { "description": "Region/state targets.", "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] }, "zips": { "description": "Zip/postal code targets.", "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "geo_regions": { "items": { "description": "A Meta geo target entry (region, city, or zip).", "properties": { "country": { "description": "Country code for this entry.", "type": [ "string", "null" ] }, "key": { "description": "Meta geo target key/ID.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "radius": { "description": "Radius in miles (cities only).", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "key" ], "type": "object" }, "type": [ "array", "null" ] }, "geo_zips": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "instagram_actor_id": { "description": "Instagram account ID for this ad set.", "type": [ "string", "null" ] }, "instagram_positions": { "description": "Instagram ad placements (stream, story, reels, etc.).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "ios_devices": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "is_dynamic_creative": { "description": "Represents `true` or `false` values.", "type": [ "boolean", "null" ] }, "lead_conversion_location": { "oneOf": [ { "$ref": "#/components/schemas/MetaAdGroupPlatformConfigLeadConversionLocation" }, { "type": "null" } ] }, "lead_form_config": { "description": "Configuration for a Meta lead gen instant form.", "properties": { "background_image_source": { "description": "Background image source: from_ad or custom.", "type": [ "string", "null" ] }, "background_image_url": { "description": "URL of custom background image.", "type": [ "string", "null" ] }, "conditional_logic_enabled": { "description": "Whether conditional logic is enabled for questions.", "type": [ "boolean", "null" ] }, "context_card_button_text": { "description": "CTA button text on the greeting card.", "type": [ "string", "null" ] }, "context_card_content": { "description": "Optional greeting card bullet points.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "context_card_style": { "description": "Greeting layout: PARAGRAPH_STYLE or LIST_STYLE.", "type": [ "string", "null" ] }, "context_card_title": { "description": "Optional greeting card title.", "type": [ "string", "null" ] }, "custom_disclaimer_body": { "description": "Custom disclaimer body text.", "type": [ "string", "null" ] }, "custom_disclaimer_checkboxes": { "description": "Consent checkboxes for the custom disclaimer.", "items": { "description": "A consent checkbox for the custom disclaimer section.", "properties": { "is_checked_by_default": { "description": "Whether the checkbox is checked by default.", "type": [ "boolean", "null" ] }, "is_required": { "description": "Whether the checkbox must be checked to submit.", "type": [ "boolean", "null" ] }, "key": { "description": "Unique key for this checkbox.", "type": "string" }, "text": { "description": "Label text for the checkbox.", "type": "string" } }, "required": [ "key", "text" ], "type": "object" }, "type": [ "array", "null" ] }, "custom_disclaimer_title": { "description": "Custom disclaimer section title.", "type": [ "string", "null" ] }, "form_type": { "description": "Form type: more_volume, higher_intent, or rich_creative.", "type": [ "string", "null" ] }, "messenger_enabled": { "description": "Enable Messenger follow-up after form submission.", "type": [ "boolean", "null" ] }, "name": { "description": "Name of the lead form.", "type": "string" }, "phone_verification_enabled": { "description": "Require phone number verification via OTP (higher_intent only).", "type": [ "boolean", "null" ] }, "privacy_policy_link_text": { "description": "Custom link text for privacy policy (max 70 chars).", "type": [ "string", "null" ] }, "privacy_policy_url": { "description": "URL to your privacy policy. Required by Meta.", "type": "string" }, "question_page_custom_headline": { "description": "Custom headline for the questions page.", "type": [ "string", "null" ] }, "questions": { "description": "Questions to ask on the form.", "items": { "description": "A question on a Meta lead gen form.", "properties": { "conditional_questions_group_id": { "description": "Group ID for conditional question routing.", "type": [ "string", "null" ] }, "dependent_conditional_questions": { "description": "Questions shown conditionally based on this question's answer.", "items": { "description": "A dependent conditional question (non-recursive to avoid schema recursion).", "properties": { "inline_context": { "description": "Helper text shown below the question.", "type": [ "string", "null" ] }, "key": { "description": "Unique key for this question.", "type": [ "string", "null" ] }, "label": { "description": "Custom label for CUSTOM questions.", "type": [ "string", "null" ] }, "options": { "description": "Answer options for multiple choice questions.", "items": { "description": "An answer option for a multiple choice lead form question.", "properties": { "key": { "description": "Unique key for this option.", "type": "string" }, "logic": { "description": "Conditional logic routing for this answer option.", "properties": { "target_end_page_index": { "description": "Index of the end page to route to (for submit_form type).", "example": 42, "type": [ "integer", "null" ] }, "target_question_index": { "description": "Index of the question to route to (for go_to_question type).", "example": 42, "type": [ "integer", "null" ] }, "type": { "description": "Logic type: go_to_question, submit_form, or close_form.", "type": "string" } }, "required": [ "type" ], "type": [ "object", "null" ] }, "value": { "description": "Display text for this option.", "type": "string" } }, "required": [ "key", "value" ], "type": "object" }, "type": [ "array", "null" ] }, "type": { "description": "Question type (EMAIL, FULL_NAME, PHONE, CUSTOM, DATE_TIME, etc.).", "type": "string" } }, "required": [ "type" ], "type": "object" }, "type": [ "array", "null" ] }, "inline_context": { "description": "Helper text shown below the question.", "type": [ "string", "null" ] }, "key": { "description": "Unique key for this question.", "type": [ "string", "null" ] }, "label": { "description": "Custom label for CUSTOM questions.", "type": [ "string", "null" ] }, "options": { "description": "Answer options for multiple choice CUSTOM questions.", "items": { "description": "An answer option for a multiple choice lead form question.", "properties": { "key": { "description": "Unique key for this option.", "type": "string" }, "logic": { "description": "Conditional logic routing for this answer option.", "properties": { "target_end_page_index": { "description": "Index of the end page to route to (for submit_form type).", "example": 42, "type": [ "integer", "null" ] }, "target_question_index": { "description": "Index of the question to route to (for go_to_question type).", "example": 42, "type": [ "integer", "null" ] }, "type": { "description": "Logic type: go_to_question, submit_form, or close_form.", "type": "string" } }, "required": [ "type" ], "type": [ "object", "null" ] }, "value": { "description": "Display text for this option.", "type": "string" } }, "required": [ "key", "value" ], "type": "object" }, "type": [ "array", "null" ] }, "question_format": { "description": "UI hint: short_answer, multiple_choice, or appointment.", "type": [ "string", "null" ] }, "type": { "description": "Question type (EMAIL, FULL_NAME, PHONE, CUSTOM, DATE_TIME, etc.).", "type": "string" } }, "required": [ "type" ], "type": "object" }, "type": "array" }, "rich_creative_headline": { "description": "Headline for rich creative form intro.", "type": [ "string", "null" ] }, "rich_creative_overview": { "description": "Overview description for rich creative form intro.", "type": [ "string", "null" ] }, "rich_creative_url": { "description": "Uploaded image URL for rich creative form type.", "type": [ "string", "null" ] }, "thank_you_pages": { "description": "Thank you / ending pages (supports multiple for conditional routing).", "items": { "description": "A thank-you / ending page for a Meta lead gen form.", "properties": { "body": { "description": "Body text for this ending page.", "type": [ "string", "null" ] }, "business_phone": { "description": "Business phone number for call CTA.", "type": [ "string", "null" ] }, "button_text": { "description": "Custom button text.", "type": [ "string", "null" ] }, "button_type": { "description": "CTA button type: VIEW_WEBSITE, CALL_BUSINESS, DOWNLOAD.", "type": [ "string", "null" ] }, "conditional_question_group_id": { "description": "Question group ID for conditional routing to this page.", "type": [ "string", "null" ] }, "enable_messenger": { "description": "Enable Messenger follow-up.", "type": [ "boolean", "null" ] }, "gated_file_url": { "description": "Uploaded file URL for gated content download.", "type": [ "string", "null" ] }, "link": { "description": "URL the button links to.", "type": [ "string", "null" ] }, "name": { "description": "Internal name for this ending page.", "type": [ "string", "null" ] }, "title": { "description": "Headline for this ending page.", "type": [ "string", "null" ] } }, "required": [], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "name", "privacy_policy_url", "questions" ], "type": [ "object", "null" ] }, "lead_gen_form_id": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "lifetime_budget": { "description": "Lifetime budget in cents.", "example": 42, "type": [ "integer", "null" ] }, "lifetime_min_spend_target": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "lifetime_spend_cap": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "location_types": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "messenger_positions": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "optimization_goal": { "description": "What this ad set optimizes for on Meta.", "oneOf": [ { "$ref": "#/components/schemas/MetaAdGroupPlatformConfigOptimizationGoal" }, { "type": "null" } ] }, "page_id": { "description": "Facebook Page ID for this ad set.", "type": [ "string", "null" ] }, "pixel_id": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "promoted_object": { "description": "The object this ad set promotes (pixel, page, etc.).", "properties": { "custom_conversion_id": { "description": "Custom conversion rule ID (numeric, from Meta Events Manager).", "type": [ "string", "null" ] }, "custom_event_str": { "description": "Pixel event name, used when custom_event_type is OTHER.", "type": [ "string", "null" ] }, "custom_event_type": { "description": "Custom event type (e.g., PURCHASE, COMPLETE_REGISTRATION, OTHER).", "type": [ "string", "null" ] }, "page_id": { "description": "Facebook Page ID.", "type": [ "string", "null" ] }, "pixel_id": { "description": "Meta Pixel ID for conversion tracking.", "type": [ "string", "null" ] }, "whatsapp_phone_number": { "description": "WhatsApp phone number for messaging campaigns.", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "publisher_platforms": { "description": "Platforms to publish on (facebook, instagram, messenger, audience_network).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "source_adset_id": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "start_time": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "status": { "oneOf": [ { "$ref": "#/components/schemas/MetaAdGroupPlatformConfigStatus" }, { "type": "null" } ] }, "targeting_automation": { "description": "Advantage+ audience expansion settings.", "properties": { "advantage_audience": { "description": "0 = off (use exact targeting), 1 = on (let Meta expand audience).", "example": 42, "type": [ "integer", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "threads_positions": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "updated_time": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "user_device": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "user_os": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "whatsapp_phone_number": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "whatsapp_positions": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "tiktok": { "description": "TikTok ad group configuration.", "properties": { "actions": { "items": { "description": "A single TikTok behavioral targeting entry. One category of past user behavior (what they did, over what window, on which kind of content). See docs/tiktok_api/ad_group.md § actions.", "properties": { "action_category_ids": { "description": "Behavioral category IDs. Use /tool/action_category/ to list them.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "action_period": { "description": "Lookback window in days. TikTok accepts 7, 15, 30, 60, 90, or 180.", "example": 42, "type": [ "integer", "null" ] }, "action_scene": { "description": "Behavior scene (VIDEO_RELATED, CREATOR_RELATED, HASHTAG_RELATED, LIVE_RELATED).", "oneOf": [ { "$ref": "#/components/schemas/TiktokActionScene" }, { "type": "null" } ] }, "video_user_actions": { "description": "Specific video interactions (WATCHED_TO_END, LIKED, COMMENTED, SHARED, FOLLOWED, PROFILE_VISITED).", "items": { "$ref": "#/components/schemas/TiktokVideoUserAction" }, "type": [ "array", "null" ] } }, "required": [], "type": "object" }, "type": [ "array", "null" ] }, "age_groups": { "items": { "$ref": "#/components/schemas/TiktokAgeGroup" }, "type": [ "array", "null" ] }, "app_id": { "description": "App ID for app promotion campaigns.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "attribution_event_count": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigAttributionEventCount" }, { "type": "null" } ] }, "audience_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "audience_rule": { "additionalProperties": true, "description": "Represents untyped JSON", "type": [ "object", "null" ] }, "audience_type": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigAudienceType" }, { "type": "null" } ] }, "bid_price": { "description": "Bid price (cost per result for Cost Cap).", "example": 6.9, "type": [ "number", "null" ] }, "bid_type": { "description": "Bidding strategy (BID_TYPE_NO_BID, BID_TYPE_CUSTOM).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigBidType" }, { "type": "null" } ] }, "billing_event": { "description": "How you are billed on TikTok (CPC, CPM, OCPM, CPV).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigBillingEvent" }, { "type": "null" } ] }, "brand_safety_type": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigBrandSafetyType" }, { "type": "null" } ] }, "budget_mode": { "description": "Budget mode (BUDGET_MODE_DAY, BUDGET_MODE_TOTAL, BUDGET_MODE_DYNAMIC_DAILY_BUDGET).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigBudgetMode" }, { "type": "null" } ] }, "carrier_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "category_exclusion_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "click_attribution_window": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigClickAttributionWindow" }, { "type": "null" } ] }, "comment_disabled": { "description": "Represents `true` or `false` values.", "type": [ "boolean", "null" ] }, "contextual_tag_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "conversion_bid_price": { "description": "Target cost per conversion for oCPM.", "example": 6.9, "type": [ "number", "null" ] }, "creative_material_mode": { "description": "Creative delivery strategy.", "type": [ "string", "null" ] }, "dayparting": { "description": "Ad delivery schedule (48x7 character string).", "type": [ "string", "null" ] }, "deep_funnel_event_source": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "deep_funnel_event_source_id": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "deep_funnel_optimization_status": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigDeepFunnelOptimizationStatus" }, { "type": "null" } ] }, "device_model_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "device_price_ranges": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "engaged_view_attribution_window": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigEngagedViewAttributionWindow" }, { "type": "null" } ] }, "excluded_audience_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "excluded_location_ids": { "description": "TikTok location/region IDs to exclude.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "frequency": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": [ "integer", "null" ] }, "frequency_schedule": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": [ "integer", "null" ] }, "gender": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigGender" }, { "type": "null" } ] }, "identity_authorized_bc_id": { "description": "Business Center ID for BC_AUTH_TT identity.", "type": [ "string", "null" ] }, "identity_id": { "description": "TikTok identity ID for the ad group.", "type": [ "string", "null" ] }, "identity_type": { "description": "Identity type (AUTH_CODE, TT_USER, BC_AUTH_TT).", "type": [ "string", "null" ] }, "instant_form_config": { "description": "Instant form configuration for lead generation campaigns.", "properties": { "button_text": { "description": "Submit button text.", "type": [ "string", "null" ] }, "greeting": { "description": "Greeting text shown at the top of the form.", "type": [ "string", "null" ] }, "name": { "description": "Form name. Auto-generated if omitted.", "type": [ "string", "null" ] }, "privacy_policy_url": { "description": "URL to your privacy policy.", "type": "string" }, "questions": { "description": "Form questions (at least one required).", "items": { "description": "A question for a TikTok instant form.", "properties": { "field_type": { "description": "Question type (EMAIL, PHONE_NUMBER, NAME, CUSTOM).", "type": "string" }, "label": { "description": "Custom label for the question.", "type": [ "string", "null" ] } }, "required": [ "field_type" ], "type": "object" }, "type": "array" } }, "required": [ "privacy_policy_url", "questions" ], "type": [ "object", "null" ] }, "instant_form_id": { "description": "TikTok instant form ID (set automatically when instant_form_config is provided).", "type": [ "string", "null" ] }, "interest_category_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "interest_keyword_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "inventory_filter_enabled": { "description": "Represents `true` or `false` values.", "type": [ "boolean", "null" ] }, "ios14_targeting": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigIos14Targeting" }, { "type": "null" } ] }, "isp_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "languages": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "location_ids": { "description": "TikTok location/region IDs for geo targeting.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "min_android_version": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "min_ios_version": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "network_types": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "operating_systems": { "items": { "$ref": "#/components/schemas/TiktokOperatingSystem" }, "type": [ "array", "null" ] }, "operation_status": { "description": "Initial status (ENABLE, DISABLE).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigOperationStatus" }, { "type": "null" } ] }, "optimization_event": { "description": "Conversion event (e.g., COMPLETE_PAYMENT).", "type": [ "string", "null" ] }, "optimization_goal": { "description": "What this ad group optimizes for on TikTok.", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigOptimizationGoal" }, { "type": "null" } ] }, "pacing": { "description": "Budget pacing (PACING_MODE_SMOOTH, PACING_MODE_FAST).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigPacing" }, { "type": "null" } ] }, "pangle_audience_package_exclude_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "pangle_audience_package_include_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "pangle_block_app_ids": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "pixel_id": { "description": "TikTok Pixel ID for conversion tracking.", "type": [ "string", "null" ] }, "placement_type": { "description": "Placement strategy (PLACEMENT_TYPE_AUTOMATIC, PLACEMENT_TYPE_NORMAL).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigPlacementType" }, { "type": "null" } ] }, "placements": { "description": "Placements (PLACEMENT_TIKTOK, PLACEMENT_PANGLE, etc.).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "product_set_id": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "product_source": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigProductSource" }, { "type": "null" } ] }, "promotion_type": { "description": "Promotion type (optimization location).", "type": [ "string", "null" ] }, "schedule_end_time": { "description": "Schedule end time (UTC, YYYY-MM-DD HH:MM:SS).", "type": [ "string", "null" ] }, "schedule_start_time": { "description": "Schedule start time (UTC, YYYY-MM-DD HH:MM:SS).", "type": [ "string", "null" ] }, "schedule_type": { "description": "Schedule type (SCHEDULE_START_END, SCHEDULE_FROM_NOW).", "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigScheduleType" }, { "type": "null" } ] }, "secondary_optimization_event": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "shopping_ads_retargeting_actions_days": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": [ "integer", "null" ] }, "shopping_ads_retargeting_type": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigShoppingAdsRetargetingType" }, { "type": "null" } ] }, "spending_power": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigSpendingPower" }, { "type": "null" } ] }, "tiktok_subplacements": { "description": "TikTok subplacements (IN_FEED, SEARCH_FEED, etc.).", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "vertical_sensitivity_id": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": [ "string", "null" ] }, "video_download_disabled": { "description": "Represents `true` or `false` values.", "type": [ "boolean", "null" ] }, "video_user_actions": { "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "view_attribution_window": { "oneOf": [ { "$ref": "#/components/schemas/TiktokAdGroupPlatformConfigViewAttributionWindow" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "status": { "description": "Status of the ad group.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupStatuses" }, { "type": "null" } ] }, "title": { "description": "Human-readable ad group title.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update", "ad_campaign:basic:read" ] } ], "summary": "Update ad group", "tags": [ "Ad groups" ], "x-group-title": "Ads" } }, "/ad_groups/{id}/pause": { "post": { "description": "Pauses an ad group.\n\nRequired permissions:\n - `ad_campaign:update`\n - `ad_campaign:basic:read`", "operationId": "pauseAdGroup", "parameters": [ { "description": "The unique identifier of the ad group to pause.", "in": "path", "name": "id", "required": true, "schema": { "example": "adgrp_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update", "ad_campaign:basic:read" ] } ], "summary": "Pause ad group", "tags": [ "Ad groups" ], "x-group-title": "Ads" } }, "/ad_groups/{id}/unpause": { "post": { "description": "Resumes a paused ad group.\n\nRequired permissions:\n - `ad_campaign:update`\n - `ad_campaign:basic:read`", "operationId": "unpauseAdGroup", "parameters": [ { "description": "The unique identifier of the ad group to unpause.", "in": "path", "name": "id", "required": true, "schema": { "example": "adgrp_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update", "ad_campaign:basic:read" ] } ], "summary": "Unpause ad group", "tags": [ "Ad groups" ], "x-group-title": "Ads" } }, "/ad_reports": { "get": { "description": "Performance report for a company, ad campaigns, ad groups, or ads. Always returns aggregate `summary` totals summed across the scope. Set `granularity` to additionally get a time series, or set `breakdown` (`campaign`/`ad_group`/`ad`) to additionally get per-entity rows inside the requested scope. Exactly one of `companyId`, `adCampaignIds`, `adGroupIds`, or `adIds` must be provided.\n\nRequired permissions:\n - `ad_campaign:stats:read`", "operationId": "retrieveAdReport", "parameters": [ { "explode": true, "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "description": "Scope the report to these ad campaigns (max 100); stats are summed across them. Mutually exclusive with `companyId`, `adGroupIds`, and `adIds`.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_group_ids", "required": false, "schema": { "description": "Scope the report to these ad groups (max 100); stats are summed across them. Mutually exclusive with `companyId`, `adCampaignIds`, and `adIds`.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_ids", "required": false, "schema": { "description": "Scope the report to these ads (max 100); stats are summed across them. Mutually exclusive with `companyId`, `adCampaignIds`, and `adGroupIds`.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "breakdown", "required": false, "schema": { "description": "Entity level to break down the report by. When set, `breakdown` on the response contains one row per entity at the requested level inside the requested scope. `ad` returns one row per ad, `ad_group` per ad group, `campaign` per ad campaign. The breakdown level must be at or below the scope (e.g. `adId` cannot be broken down by `campaign`). The `summary` totals are unaffected.", "oneOf": [ { "$ref": "#/components/schemas/AdReportBreakdownLevels" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of a company. Mutually exclusive with `adCampaignIds`, `adGroupIds`, and `adIds`. Use with `breakdown` to fan out across every campaign, ad group, or ad in the company without paging.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "currency", "required": false, "schema": { "description": "ISO 4217 currency code to report `spend` in. Defaults to the company's ads reporting currency.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "from", "required": true, "schema": { "description": "Inclusive start of the reporting window.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "granularity", "required": false, "schema": { "description": "Bucket grain for the per-bucket `granularity` time series. Omit (`null`) for summary-only. `hourly`/`daily` max 90 days, `weekly` max 366 days, `monthly` max 4 years. The `summary` totals are unaffected. With `breakdown`, each row gets its own series at the same grain.", "oneOf": [ { "$ref": "#/components/schemas/Granularities" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "to", "required": true, "schema": { "description": "Inclusive end of the reporting window.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdReport" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:stats:read" ] } ], "summary": "Retrieve ad report", "tags": [ "Ad reports" ], "x-group-title": "Ads" } }, "/ads": { "get": { "description": "List ads scoped by ad group, campaign, or company.\n\nRequired permissions:\n - `ad_campaign:basic:read`", "operationId": "listAd", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "description": "Only return ads belonging to these ad campaigns (max 100). Can be combined with companyId or used on its own.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_group_id", "required": false, "schema": { "description": "Filter by ad group. Provide exactly one of ad_group_id, ad_campaign_id, or company_id.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_group_ids", "required": false, "schema": { "description": "Only return ads belonging to these ad groups (max 100). Can be combined with companyId or used on its own.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Filter by company. Provide exactly one of ad_group_id, ad_campaign_id, or company_id.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return ads created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return ads created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to order results by, such as creation date.", "oneOf": [ { "$ref": "#/components/schemas/AdOrder" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Case-insensitive substring match against the ad title or ID.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_from", "required": false, "schema": { "description": "Inclusive start of the window for each ad's metric fields (spend, impressions, …) and for stats-column sorting. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_to", "required": false, "schema": { "description": "Inclusive end of the window for each ad's metric fields and for stats-column sorting. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter by status.", "oneOf": [ { "$ref": "#/components/schemas/ExternalAdStatuses" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "campaign_id", "required": false, "schema": { "description": "Filter by campaign.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order_by", "required": false, "schema": { "description": "Server-side sort column.", "oneOf": [ { "$ref": "#/components/schemas/ExternalAdSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order_direction", "required": false, "schema": { "description": "Sort direction.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "ad_campaign_id", "required": false, "schema": { "description": "Filter by ad campaign. Provide exactly one of ad_group_id, ad_campaign_id, or company_id.", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ExternalAd.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AdListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List ads", "tags": [ "Ads" ], "x-group-title": "Ads" } }, "/ads/{id}": { "get": { "description": "Retrieve an ad by its unique identifier.\n\nRequired permissions:\n - `ad_campaign:basic:read`", "operationId": "retrieveAd", "parameters": [ { "description": "The unique identifier of the ad.", "in": "path", "name": "id", "required": true, "schema": { "example": "ad_xxxxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "stats_from", "required": false, "schema": { "description": "Inclusive start of the window for the ad's metric fields (spend, impressions, …). Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "stats_to", "required": false, "schema": { "description": "Inclusive end of the window for the ad's metric fields. Omit both statsFrom and statsTo for all-time stats.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve ad", "tags": [ "Ads" ], "x-group-title": "Ads" } }, "/ads/{id}/pause": { "post": { "description": "Pauses an ad.\n\nRequired permissions:\n - `ad_campaign:update`\n - `ad_campaign:basic:read`", "operationId": "pauseAd", "parameters": [ { "description": "The unique identifier of the ad to pause.", "in": "path", "name": "id", "required": true, "schema": { "example": "ad_xxxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update", "ad_campaign:basic:read" ] } ], "summary": "Pause ad", "tags": [ "Ads" ], "x-group-title": "Ads" } }, "/ads/{id}/unpause": { "post": { "description": "Resumes a paused ad.\n\nRequired permissions:\n - `ad_campaign:update`\n - `ad_campaign:basic:read`", "operationId": "unpauseAd", "parameters": [ { "description": "The unique identifier of the ad to unpause.", "in": "path", "name": "id", "required": true, "schema": { "example": "ad_xxxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ad_campaign:update", "ad_campaign:basic:read" ] } ], "summary": "Unpause ad", "tags": [ "Ads" ], "x-group-title": "Ads" } }, "/affiliates": { "get": { "description": "Returns a paginated list of affiliates for the actor in context, with optional filtering by status, search, and sorting.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "listAffiliate", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list affiliates for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to sort results by.", "oneOf": [ { "$ref": "#/components/schemas/AffiliatesSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Search affiliates by username.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter by affiliate status (active or archived).", "oneOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Affiliate.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AffiliateListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "List affiliates", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "post": { "description": "Creates or finds an affiliate for a company and user.\n\nRequired permissions:\n - `affiliate:create`", "operationId": "createAffiliate", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAffiliateRecord", "properties": { "company_id": { "description": "The ID of the company to create the affiliate for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "user_identifier": { "description": "The user identifier (username, email, user ID, or Discord ID).", "type": "string" } }, "required": [ "company_id", "user_identifier" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Affiliate" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:create" ] } ], "summary": "Create affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}": { "get": { "description": "Retrieves the details of an existing affiliate.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "retrieveAffiliate", "parameters": [ { "description": "The unique identifier of the affiliate.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Affiliate" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "Retrieve affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/archive": { "post": { "description": "Archives an existing Affiliate\n\nRequired permissions:\n - `affiliate:update`", "operationId": "archiveAffiliate", "parameters": [ { "description": "The internal ID of the affiliate to archive.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Archive affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/overrides": { "get": { "description": "Returns a paginated list of overrides for an affiliate.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "listOverridesAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "override_type", "required": false, "schema": { "description": "Filter by override type (standard or rev_share).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateOverrideRoles" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AffiliateOverride.", "properties": { "data": { "description": "A list of nodes.", "items": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "List overrides", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "post": { "description": "Creates a commission override for an affiliate.\n\nRequired permissions:\n - `affiliate:create`", "operationId": "createOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAffiliateOverride", "oneOf": [ { "description": "Autogenerated input type of CreateAffiliateOverride", "properties": { "applies_to_payments": { "description": "Whether commission applies to first payment or all payments (standard only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "commission_type": { "description": "The commission type (percentage or flat_fee).", "oneOf": [ { "$ref": "#/components/schemas/AffiliatePayoutTypes" }, { "type": "null" } ] }, "commission_value": { "description": "The commission value (percentage 1-100 or flat fee).", "example": 6.9, "type": "number" }, "id": { "description": "The affiliate ID.", "type": "string" }, "override_type": { "const": "standard", "type": "string" }, "plan_id": { "description": "The plan ID (required for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "commission_value", "id", "override_type", "plan_id" ], "title": "CreateAffiliateOverrideInputOverrideTypeStandard", "type": "object" }, { "description": "Autogenerated input type of CreateAffiliateOverride", "properties": { "commission_type": { "description": "The commission type (percentage or flat_fee).", "oneOf": [ { "$ref": "#/components/schemas/AffiliatePayoutTypes" }, { "type": "null" } ] }, "commission_value": { "description": "The commission value (percentage 1-100 or flat fee).", "example": 6.9, "type": "number" }, "id": { "description": "The affiliate ID.", "type": "string" }, "override_type": { "const": "rev_share", "type": "string" }, "product_id": { "description": "The product ID (for rev-share overrides, omit for company-wide).", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis for rev-share overrides. Defaults to post_fees.", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] } }, "required": [ "commission_value", "id", "override_type" ], "title": "CreateAffiliateOverrideInputOverrideTypeRevShare", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:create" ] } ], "summary": "Create override", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/overrides/{override_id}": { "delete": { "description": "Deletes an affiliate override.\n\nRequired permissions:\n - `affiliate:update`", "operationId": "deleteOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The override ID.", "in": "path", "name": "override_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Delete override", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "get": { "description": "Retrieves the details of a specific affiliate override.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "retrieveOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The override ID.", "in": "path", "name": "override_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "Retrieve override", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "patch": { "description": "Updates an existing affiliate override.\n\nRequired permissions:\n - `affiliate:update`", "operationId": "updateOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The override ID.", "in": "path", "name": "override_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAffiliateOverride", "properties": { "applies_to_payments": { "description": "Whether commission applies to first payment or all payments (standard only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "commission_type": { "description": "The commission type (percentage or flat_fee).", "oneOf": [ { "$ref": "#/components/schemas/AffiliatePayoutTypes" }, { "type": "null" } ] }, "commission_value": { "description": "The commission value (percentage 1-100 or flat fee in dollars).", "example": 6.9, "type": [ "number", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Update override", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/unarchive": { "post": { "description": "Unarchives an existing Affiliate\n\nRequired permissions:\n - `affiliate:update`", "operationId": "unarchiveAffiliate", "parameters": [ { "description": "The internal ID of the affiliate to archive.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Unarchive affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/ai_chats": { "get": { "description": "Returns a paginated list of AI chat threads for the current authenticated user.", "operationId": "listAiChat", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "only_active_crons", "required": false, "schema": { "description": "When true, returns only chats with an active cron schedule", "type": [ "boolean", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AiChat.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AiChatListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List ai chats", "tags": [ "Ai chats" ], "x-group-title": "AI" }, "post": { "description": "Create a new AI chat thread and send the first message to the AI agent.\n\nRequired permissions:\n - `ai_chat:create`", "operationId": "createAiChat", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAiChat", "properties": { "current_company_id": { "description": "The unique identifier of the company to set as context for the AI chat (e.g., \"biz_XXXXX\").", "type": [ "string", "null" ] }, "message_attachments": { "description": "A list of previously uploaded file attachments to include with the first message.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "message_source": { "description": "The source of the message.", "oneOf": [ { "$ref": "#/components/schemas/AiChatMessageSourceTypes" }, { "type": "null" } ] }, "message_text": { "description": "The text content of the first message to send to the AI agent.", "type": "string" }, "suggestion_type": { "description": "The type of suggestion prompt that was clicked, when message_source is 'suggestion'.", "type": [ "string", "null" ] }, "title": { "description": "An optional display title for the AI chat thread (e.g., \"Help with billing\").", "type": [ "string", "null" ] } }, "required": [ "message_text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChat" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ai_chat:create" ] } ], "summary": "Create ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" } }, "/ai_chats/{id}": { "delete": { "description": "Delete an AI chat thread so it no longer appears in the user's chat list.\n\nRequired permissions:\n - `ai_chat:delete`", "operationId": "deleteAiChat", "parameters": [ { "description": "The unique identifier of the AI chat to delete (e.g., \"ai_chat_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "aich_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ai_chat:delete" ] } ], "summary": "Delete ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" }, "get": { "description": "Retrieves the details of an existing AI chat.", "operationId": "retrieveAiChat", "parameters": [ { "description": "The unique identifier of the AI chat to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "aich_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChat" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" }, "patch": { "description": "Update an AI chat's title, notification preferences, or associated company context.\n\nRequired permissions:\n - `ai_chat:update`", "operationId": "updateAiChat", "parameters": [ { "description": "The unique identifier of the AI chat to update (e.g., \"ai_chat_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "aich_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAiChat", "properties": { "current_company_id": { "description": "The unique identifier of the company to set as context for the AI chat (e.g., \"biz_XXXXX\").", "type": [ "string", "null" ] }, "notification_preference": { "description": "The notification preference for the AI chat.", "oneOf": [ { "$ref": "#/components/schemas/AiChatNotificationPreferences" }, { "type": "null" } ] }, "title": { "description": "The new display title for the AI chat thread (e.g., \"Help with billing\").", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChat" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ai_chat:update" ] } ], "summary": "Update ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" } }, "/app_builds": { "get": { "description": "Returns a paginated list of build artifacts for a given app, with optional filtering by platform, status, and creation date.\n\nRequired permissions:\n - `developer:manage_builds`", "operationId": "listAppBuild", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "app_id", "required": true, "schema": { "description": "The unique identifier of the app to list builds for.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "platform", "required": false, "schema": { "description": "Filter builds by target platform.", "oneOf": [ { "$ref": "#/components/schemas/AppBuildPlatforms" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter builds by review status.", "oneOf": [ { "$ref": "#/components/schemas/AppBuildStatuses" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return builds created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return builds created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AppBuild.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AppBuildListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "List app builds", "tags": [ "App builds" ], "x-group-title": "Developer" }, "post": { "description": "Upload a new build artifact for an app. The build must include a compiled code bundle for the specified platform.\n\nRequired permissions:\n - `developer:manage_builds`", "operationId": "createAppBuild", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAppBuild", "properties": { "ai_prompt_id": { "description": "The identifier of the AI prompt that generated this build, if applicable.", "example": "prmt_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "app_id": { "description": "The unique identifier of the app to create the build for. Defaults to the app associated with the current API key.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "attachment": { "description": "The build file to upload. For iOS and Android, this should be a .zip archive containing a main_js_bundle.hbc file and an optional assets folder. For web, this should be a JavaScript file.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "checksum": { "description": "A client-generated checksum of the build file, used to verify file integrity when unpacked on a device.", "type": "string" }, "platform": { "$ref": "#/components/schemas/AppBuildPlatforms", "description": "The target platform for the build. Accepted values: ios, android, web." }, "supported_app_view_types": { "description": "The view types this build supports. A build can support multiple view types but should only list the ones its code implements.", "items": { "$ref": "#/components/schemas/AppViewTypes" }, "type": [ "array", "null" ] } }, "required": [ "attachment", "checksum", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Create app build", "tags": [ "App builds" ], "x-group-title": "Developer" } }, "/app_builds/{id}": { "get": { "description": "Retrieves the details of an existing app build.\n\nRequired permissions:\n - `developer:manage_builds`", "operationId": "retrieveAppBuild", "parameters": [ { "description": "The unique identifier of the app build to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "apbu_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Retrieve app build", "tags": [ "App builds" ], "x-group-title": "Developer" } }, "/app_builds/{id}/promote": { "post": { "description": "Promote an approved or draft app build to production so it becomes the active version served to users.\n\nRequired permissions:\n - `developer:manage_builds`", "operationId": "promoteAppBuild", "parameters": [ { "description": "The unique identifier of the app build to promote to production, starting with 'abld_'.", "in": "path", "name": "id", "required": true, "schema": { "example": "apbu_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Promote app build", "tags": [ "App builds" ], "x-group-title": "Developer" } }, "/apps": { "get": { "description": "Returns a paginated list of apps on the Whop platform, with optional filtering by company, type, view support, and search query.", "operationId": "listApp", "parameters": [ { "explode": true, "in": "query", "name": "app_type", "required": false, "schema": { "description": "Filter apps by the type of end-user they are built for, such as consumer or business.", "oneOf": [ { "$ref": "#/components/schemas/AppTypes" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Filter apps to only those created by this company, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Accepted values: asc, desc.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to sort apps by. Defaults to discoverable_at descending, showing the most recently published apps first.", "oneOf": [ { "$ref": "#/components/schemas/AppOrder" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "A search string to filter apps by name, such as 'chat' or 'analytics'.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "verified_apps_only", "required": false, "schema": { "description": "Whether to only return apps that have been verified by Whop. Useful for populating a featured apps section.", "type": [ "boolean", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "view_type", "required": false, "schema": { "description": "Filter apps to only those supporting a specific view type, such as 'dashboard' or 'hub'.", "oneOf": [ { "$ref": "#/components/schemas/AppViewTypes" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicApp.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AppListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List apps", "tags": [ "Apps" ], "x-group-title": "Developer" }, "post": { "description": "Register a new app on the Whop developer platform. Apps provide custom experiences that can be added to products.\n\nRequired permissions:\n - `developer:create_app`\n - `developer:manage_api_key`", "operationId": "createApp", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateApp", "properties": { "base_url": { "description": "The base production URL where the app is hosted, such as 'https://myapp.example.com'.", "type": [ "string", "null" ] }, "company_id": { "description": "The unique identifier of the company to create the app for, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "icon": { "description": "The icon image for the app in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "name": { "description": "The display name for the app, shown to users on the app store and product pages.", "type": "string" }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs that users are redirected to after authorizing the app.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "company_id", "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:create_app", "developer:manage_api_key" ] } ], "summary": "Create app", "tags": [ "Apps" ], "x-group-title": "Developer" } }, "/apps/{id}": { "get": { "description": "Retrieves the details of an existing app.\n\nRequired permissions:\n - `developer:manage_api_key`", "operationId": "retrieveApp", "parameters": [ { "description": "The unique identifier of the app to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "app_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Retrieve app", "tags": [ "Apps" ], "x-group-title": "Developer" }, "patch": { "description": "Update the settings, metadata, or status of an existing app on the Whop developer platform.\n\nRequired permissions:\n - `developer:update_app`\n - `developer:manage_api_key`", "operationId": "updateApp", "parameters": [ { "description": "The unique identifier of the app to update, starting with 'app_'.", "in": "path", "name": "id", "required": true, "schema": { "example": "app_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateApp", "properties": { "app_store_description": { "description": "The detailed description shown on the app store's in-depth app view page.", "type": [ "string", "null" ] }, "app_type": { "description": "The type of end-user the app is built for, such as consumer or business.", "oneOf": [ { "$ref": "#/components/schemas/AppTypes" }, { "type": "null" } ] }, "base_url": { "description": "The base production URL where the app is hosted, such as 'https://myapp.example.com'.", "example": "https://example.com/path", "type": [ "string", "null" ] }, "dashboard_path": { "description": "The URL path for the company dashboard view of the app, such as '/dashboard'.", "type": [ "string", "null" ] }, "description": { "description": "A short description of the app shown in listings and search results.", "type": [ "string", "null" ] }, "discover_path": { "description": "The URL path for the discover view of the app, such as '/discover'.", "type": [ "string", "null" ] }, "experience_path": { "description": "The URL path for the member-facing hub view of the app, such as '/experiences/[experienceId]'.", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for the app, used in listings and navigation.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "name": { "description": "The display name for the app, shown to users on the app store and product pages.", "type": [ "string", "null" ] }, "oauth_client_type": { "description": "How this app authenticates at the OAuth token endpoint.", "oneOf": [ { "$ref": "#/components/schemas/AppOauthClientTypes" }, { "type": "null" } ] }, "openapi_path": { "description": "The URL path to the OpenAPI spec file of the app, such as '/assets/openapi.json'.", "type": [ "string", "null" ] }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs that users are redirected to after authorizing the app", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "required_scopes": { "description": "The permission scopes the app will request from users when they install it.", "items": { "$ref": "#/components/schemas/AppValidScopes" }, "type": [ "array", "null" ] }, "skills_path": { "description": "The URL path to the skills directory of the app, such as '/assets/skills/'.", "type": [ "string", "null" ] }, "status": { "description": "Controls the app's visibility. Set to 'live' to publish on Whop discovery (requires name, icon, and description). Set to 'unlisted' to hide from discovery while keeping the app accessible via direct link.", "oneOf": [ { "$ref": "#/components/schemas/AppStatuses" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:update_app", "developer:manage_api_key" ] } ], "summary": "Update app", "tags": [ "Apps" ], "x-group-title": "Developer" } }, "/authorized_users": { "get": { "description": "Returns a paginated list of authorized team members for a company, with optional filtering by user, role, and creation date.\n\nRequired permissions:\n - `company:authorized_user:read`\n - `member:email:read`", "operationId": "listAuthorizedUser", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list authorized users for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter results to a specific user to check if they are an authorized team member.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "role", "required": false, "schema": { "description": "Filter authorized users by their assigned role within the company.", "oneOf": [ { "$ref": "#/components/schemas/AuthorizedUserRoles" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return authorized users created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return authorized users created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AuthorizedUser.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AuthorizedUserListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:authorized_user:read", "member:email:read" ] } ], "summary": "List authorized users", "tags": [ "Authorized users" ], "x-group-title": "Identity" }, "post": { "description": "Add a new authorized user to a company.\n\nRequired permissions:\n - `authorized_user:create`\n - `member:email:read`", "operationId": "createAuthorizedUser", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAuthorizedUser", "properties": { "company_id": { "description": "The ID of the company to add the authorized user to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "role": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "The role to assign to the authorized user within the company. Supported roles: 'moderator', 'sales_manager'." }, "send_emails": { "description": "Whether to send notification emails to the user on creation.", "type": [ "boolean", "null" ] }, "user_id": { "description": "The ID of the user to add as an authorized user.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "company_id", "role", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedUser" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "authorized_user:create", "member:email:read" ] } ], "summary": "Create authorized user", "tags": [ "Authorized users" ], "x-group-title": "Identity" } }, "/authorized_users/{id}": { "delete": { "description": "Remove an authorized user from a company.\n\nRequired permissions:\n - `authorized_user:delete`", "operationId": "deleteAuthorizedUser", "parameters": [ { "description": "The ID of the authorized user or user to remove.", "in": "path", "name": "id", "required": true, "schema": { "example": "ausr_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The ID of the company the authorized user belongs to. Optional if the authorized user ID is provided.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "authorized_user:delete" ] } ], "summary": "Delete authorized user", "tags": [ "Authorized users" ], "x-group-title": "Identity" }, "get": { "description": "Retrieves the details of an existing authorized user.\n\nRequired permissions:\n - `company:authorized_user:read`\n - `member:email:read`", "operationId": "retrieveAuthorizedUser", "parameters": [ { "description": "The unique identifier of the authorized user to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "ausr_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedUser" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:authorized_user:read", "member:email:read" ] } ], "summary": "Retrieve authorized user", "tags": [ "Authorized users" ], "x-group-title": "Identity" } }, "/bounties": { "get": { "description": "Returns a paginated list of workforce bounties. When experienceId is provided, returns bounties scoped to that experience. When omitted, returns bounties with no experience.", "operationId": "listBounty", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "experience_id", "required": false, "schema": { "description": "The experience to list bounties for. When omitted, returns bounties with no experience.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter bounties by status.", "oneOf": [ { "$ref": "#/components/schemas/Statuses" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "Sort direction. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Bounty.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/BountyListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List bounties", "tags": [ "Bounties" ], "x-group-title": "Bounties" }, "post": { "description": "Create a new workforce bounty by funding a dedicated bounty pool.\n\nRequired permissions:\n - `bounty:create`", "operationId": "createBounty", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateWorkforceBounty", "properties": { "accepted_submissions_limit": { "description": "The number of submissions that can be approved before the bounty closes. Defaults to 1.", "example": 42, "type": [ "integer", "null" ] }, "allowed_country_codes": { "description": "The ISO3166 country codes where this bounty should be visible. Empty means globally visible.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "base_unit_amount": { "description": "The amount paid to each approved submission. The total bounty pool funded is this amount times accepted_submissions_limit.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency for the bounty pool funding amount." }, "description": { "description": "The description of the bounty.", "type": "string" }, "experience_id": { "description": "An optional experience to scope the bounty to.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "origin_account_id": { "description": "The user (user_*) or company (biz_*) tag whose balance funds this bounty pool. Defaults to the requester's personal balance when omitted. The requester must be the user themself or an owner/admin of the company.", "type": [ "string", "null" ] }, "post_markdown_content": { "description": "Optional markdown body for the anchor forum post. Falls back to the bounty description when omitted.", "type": [ "string", "null" ] }, "post_title": { "description": "Optional title for the anchor forum post. Falls back to the bounty title when omitted.", "type": [ "string", "null" ] }, "title": { "description": "The title of the bounty.", "type": "string" } }, "required": [ "base_unit_amount", "currency", "description", "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "bounty:create" ] } ], "summary": "Create bounty", "tags": [ "Bounties" ], "x-group-title": "Bounties" } }, "/bounties/{id}": { "get": { "description": "Retrieves a workforce bounty for the current authenticated user.", "operationId": "retrieveBounty", "parameters": [ { "description": "The unique identifier of the workforce bounty to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "bnty_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve bounty", "tags": [ "Bounties" ], "x-group-title": "Bounties" } }, "/card_transactions": { "get": { "description": "Returns a paginated list of card transactions for a company.\n\nRequired permissions:\n - `payout:account:read`", "operationId": "listCardTransaction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "card_id", "required": false, "schema": { "description": "Filter transactions to a specific card.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The company to list card transactions for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return transactions created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return transactions created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "Sort direction for results.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter by transaction lifecycle status.", "oneOf": [ { "$ref": "#/components/schemas/CardIssuingTransactionStatus" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicCardTransaction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CardTransactionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List card transactions", "tags": [ "Card transactions" ], "x-group-title": "Cards" } }, "/card_transactions/{id}": { "get": { "description": "Retrieves a single card transaction by ID.\n\nRequired permissions:\n - `payout:account:read`", "operationId": "retrieveCardTransaction", "parameters": [ { "description": "The card transaction ID (citx_xxx).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTransaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve card transaction", "tags": [ "Card transactions" ], "x-group-title": "Cards" } }, "/chat_channels": { "get": { "description": "Returns a paginated list of chat channels within a specific company, with optional filtering by product.\n\nRequired permissions:\n - `chat:read`", "operationId": "listChatChannel", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list chat channels for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": false, "schema": { "description": "The unique identifier of a product to filter by. When set, only chat channels connected to this product are returned.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ChatFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ChatChannelListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "List chat channels", "tags": [ "Chat channels" ], "x-group-title": "Engagement" } }, "/chat_channels/{id}": { "get": { "description": "Retrieves the details of an existing chat channel.\n\nRequired permissions:\n - `chat:read`", "operationId": "retrieveChatChannel", "parameters": [ { "description": "The unique identifier of the chat channel or experience to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "Retrieve chat channel", "tags": [ "Chat channels" ], "x-group-title": "Engagement" }, "patch": { "description": "Update moderation settings for a chat channel, such as who can post, banned words, and media restrictions.\n\nRequired permissions:\n - `chat:moderate`", "operationId": "updateChatChannel", "parameters": [ { "description": "The unique identifier of the chat channel to update. Accepts either an experience ID (e.g. 'exp_xxxxx') or a chat channel ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateChatChannel", "properties": { "ban_media": { "description": "Whether media uploads such as images and videos are banned in this chat channel.", "type": [ "boolean", "null" ] }, "ban_urls": { "description": "Whether URLs and links are banned from being posted in this chat channel.", "type": [ "boolean", "null" ] }, "banned_words": { "description": "A list of words that are automatically blocked from messages in this chat channel. For example, ['spam', 'scam'].", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "user_posts_cooldown_seconds": { "description": "The minimum number of seconds a user must wait between sending messages in this chat channel.", "example": 42, "type": [ "integer", "null" ] }, "who_can_post": { "description": "Controls which roles are allowed to send messages in this chat channel.", "oneOf": [ { "$ref": "#/components/schemas/WhoCanPostTypes" }, { "type": "null" } ] }, "who_can_react": { "description": "Controls which roles are allowed to add reactions to messages in this chat channel.", "oneOf": [ { "$ref": "#/components/schemas/WhoCanReactTypes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:moderate" ] } ], "summary": "Update chat channel", "tags": [ "Chat channels" ], "x-group-title": "Engagement" } }, "/checkout_configurations": { "get": { "description": "Returns a paginated list of checkout configurations for a company, with optional filtering by plan and creation date.\n\nRequired permissions:\n - `checkout_configuration:basic:read`", "operationId": "listCheckoutConfiguration", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list checkout configurations for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "plan_id", "required": false, "schema": { "description": "Filter checkout configurations to only those associated with this plan identifier.", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return checkout configurations created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return checkout configurations created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CheckoutSession.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CheckoutConfigurationListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "checkout_configuration:basic:read" ] } ], "summary": "List checkout configurations", "tags": [ "Checkout configurations" ], "x-group-title": "Payins" }, "post": { "description": "Creates a new checkout configuration\n\nRequired permissions:\n - `checkout_configuration:create`\n - `plan:create`\n - `access_pass:create`\n - `access_pass:update`\n - `checkout_configuration:basic:read`", "operationId": "createCheckoutConfiguration", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateCheckoutSession", "oneOf": [ { "description": "Autogenerated input type of CreateCheckoutSession", "properties": { "affiliate_code": { "description": "An affiliate tracking code to attribute the checkout to a specific affiliate.", "type": [ "string", "null" ] }, "allow_promo_codes": { "description": "Whether the checkout should show the promo code input field and accept promo codes. Defaults to true.", "type": [ "boolean", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this session. Overrides plan and company defaults.", "properties": { "background_color": { "description": "A hex color code for the checkout page background, applied to the order summary panel (e.g. #F4F4F5).", "type": [ "string", "null" ] }, "border_style": { "description": "The border style for buttons and inputs.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutShapes" }, { "type": "null" } ] }, "button_color": { "description": "A hex color code for the button color (e.g. #FF5733).", "type": [ "string", "null" ] }, "font_family": { "description": "The font family for the checkout page.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutFonts" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] }, "currency": { "description": "The currency for the checkout when in setup mode. Controls which currency-specific payment methods are available. Defaults to USD when in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value metadata to attach to the checkout configuration.", "type": [ "object", "null" ] }, "mode": { "const": "payment", "type": "string" }, "payment_method_configuration": { "description": "The explicit payment method configuration for the checkout session. Only applies to setup mode. If not provided, the platform or company defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan attributes to create a new plan inline for this checkout configuration.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": [ "boolean", "null" ] }, "application_fee_amount": { "description": "The application fee amount collected by the platform from this connected account. Provided as a number in dollars (e.g., 5.00 for $5.00). Must be less than the total payment amount. Only valid for connected accounts with a parent company.", "example": 6.9, "type": [ "number", "null" ] }, "billing_period": { "description": "The interval in days at which the plan charges (renewal plans). For example, 30 for monthly billing.", "example": 42, "type": [ "integer", "null" ] }, "company_id": { "description": "The company the plan should be created for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The respective currency identifier for the plan." }, "custom_fields": { "description": "An array of custom field objects.", "items": { "properties": { "field_type": { "$ref": "#/components/schemas/CustomFieldTypes", "description": "The type of the custom field." }, "id": { "description": "The ID of the custom field (if being updated)", "type": [ "string", "null" ] }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "example": 42, "type": [ "integer", "null" ] }, "placeholder": { "description": "The placeholder value of the field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": [ "boolean", "null" ] } }, "required": [ "field_type", "name" ], "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "The description of the plan.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires (for expiration-based plans). For example, 365 for a one-year access pass.", "example": 42, "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Whether to force the creation of a new plan even if one with the same attributes already exists.", "type": [ "boolean", "null" ] }, "image": { "description": "An image for the plan. This will be visible on the product page to customers.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "initial_price": { "description": "An additional amount charged upon first purchase. Provided as a number in dollars (e.g., 10.00 for $10.00).", "example": 6.9, "type": [ "number", "null" ] }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "override_tax_type": { "description": "An override for tax to specify for this specific plan.", "oneOf": [ { "$ref": "#/components/schemas/TaxTypes" }, { "type": "null" } ] }, "payment_method_configuration": { "description": "The explicit payment method configuration for the plan. If not provided, the platform or company's defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "plan_type": { "description": "Indicates if the plan is a one time payment or recurring.", "oneOf": [ { "$ref": "#/components/schemas/PlanTypes" }, { "type": "null" } ] }, "product": { "description": "Pass this object to create a new product for this plan. We will use the product external identifier to find or create an existing product.", "properties": { "collect_shipping_address": { "description": "Whether or not to collect shipping information at checkout from the customer.", "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "The custom statement descriptor for the product i.e. WHOP*SPORTS, must be between 5 and 22 characters, contain at least one letter, and not contain any of the following characters: <, >, \\, ', \"", "type": [ "string", "null" ] }, "description": { "description": "A written description of the product.", "type": [ "string", "null" ] }, "external_identifier": { "description": "A unique ID used to find or create a product. When provided during creation, we will look for an existing product with this external identifier — if found, it will be updated; otherwise, a new product will be created.", "type": "string" }, "global_affiliate_percentage": { "description": "The percentage of the revenue that goes to the global affiliate program.", "example": 6.9, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "The status of the global affiliate program for this product.", "oneOf": [ { "$ref": "#/components/schemas/GlobalAffiliateStatuses" }, { "type": "null" } ] }, "headline": { "description": "The headline of the product.", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "The ID of the product tax code to apply to this product.", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "The URL to redirect the customer to after a purchase.", "type": [ "string", "null" ] }, "route": { "description": "The route of the product.", "type": [ "string", "null" ] }, "title": { "description": "The title of the product.", "type": "string" }, "visibility": { "description": "This product will/will not be displayed publicly - default hidden.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "The product the plan is related to. Either this or product is required.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "release_method": { "description": "This is the release method the business uses to sell this plan.", "oneOf": [ { "$ref": "#/components/schemas/ReleaseMethod" }, { "type": "null" } ] }, "renewal_price": { "description": "The amount the customer is charged every billing period. Provided as a number in dollars (e.g., 9.99 for $9.99/period).", "example": 6.9, "type": [ "number", "null" ] }, "split_pay_required_payments": { "description": "The number of payments required before pausing the subscription.", "example": 42, "type": [ "integer", "null" ] }, "stock": { "description": "The number of units available for purchase. If not provided, stock is unlimited.", "example": 42, "type": [ "integer", "null" ] }, "title": { "description": "The title of the plan. This will be visible on the product page to customers.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "The number of free trial days added before a renewal plan.", "example": 42, "type": [ "integer", "null" ] }, "visibility": { "description": "Shows or hides the plan from public/business view.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [ "company_id", "currency" ], "type": "object" }, "redirect_url": { "description": "The URL to redirect the user to after checkout is completed.", "type": [ "string", "null" ] }, "source_url": { "description": "The URL of the page where the checkout is being initiated from.", "type": [ "string", "null" ] } }, "required": [ "plan" ], "title": "CreateCheckoutSessionInputModePaymentWithPlan", "type": "object" }, { "description": "Autogenerated input type of CreateCheckoutSession", "properties": { "affiliate_code": { "description": "An affiliate tracking code to attribute the checkout to a specific affiliate.", "type": [ "string", "null" ] }, "allow_promo_codes": { "description": "Whether the checkout should show the promo code input field and accept promo codes. Defaults to true.", "type": [ "boolean", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this session. Overrides plan and company defaults.", "properties": { "background_color": { "description": "A hex color code for the checkout page background, applied to the order summary panel (e.g. #F4F4F5).", "type": [ "string", "null" ] }, "border_style": { "description": "The border style for buttons and inputs.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutShapes" }, { "type": "null" } ] }, "button_color": { "description": "A hex color code for the button color (e.g. #FF5733).", "type": [ "string", "null" ] }, "font_family": { "description": "The font family for the checkout page.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutFonts" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] }, "currency": { "description": "The currency for the checkout when in setup mode. Controls which currency-specific payment methods are available. Defaults to USD when in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value metadata to attach to the checkout configuration.", "type": [ "object", "null" ] }, "mode": { "const": "payment", "type": "string" }, "payment_method_configuration": { "description": "The explicit payment method configuration for the checkout session. Only applies to setup mode. If not provided, the platform or company defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "plan_id": { "description": "The unique identifier of an existing plan to use for this checkout configuration.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "redirect_url": { "description": "The URL to redirect the user to after checkout is completed.", "type": [ "string", "null" ] }, "source_url": { "description": "The URL of the page where the checkout is being initiated from.", "type": [ "string", "null" ] } }, "required": [ "plan_id" ], "title": "CreateCheckoutSessionInputModePaymentWithPlanId", "type": "object" }, { "description": "Autogenerated input type of CreateCheckoutSession", "properties": { "allow_promo_codes": { "description": "Whether the checkout should show the promo code input field and accept promo codes. Defaults to true.", "type": [ "boolean", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this session. Overrides plan and company defaults.", "properties": { "background_color": { "description": "A hex color code for the checkout page background, applied to the order summary panel (e.g. #F4F4F5).", "type": [ "string", "null" ] }, "border_style": { "description": "The border style for buttons and inputs.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutShapes" }, { "type": "null" } ] }, "button_color": { "description": "A hex color code for the button color (e.g. #FF5733).", "type": [ "string", "null" ] }, "font_family": { "description": "The font family for the checkout page.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutFonts" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] }, "company_id": { "description": "The unique identifier of the company to create the checkout configuration for. Only required in setup mode.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "currency": { "description": "The currency for the checkout when in setup mode. Controls which currency-specific payment methods are available. Defaults to USD when in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value metadata to attach to the checkout configuration.", "type": [ "object", "null" ] }, "mode": { "const": "setup", "type": "string" }, "payment_method_configuration": { "description": "The explicit payment method configuration for the checkout session. Only applies to setup mode. If not provided, the platform or company defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "redirect_url": { "description": "The URL to redirect the user to after checkout is completed.", "type": [ "string", "null" ] }, "source_url": { "description": "The URL of the page where the checkout is being initiated from.", "type": [ "string", "null" ] }, "three_ds_level": { "description": "The 3D Secure behavior to apply when collecting a payment method. Only applies to setup mode; in payment mode the plan's 3D Secure behavior is used.", "oneOf": [ { "$ref": "#/components/schemas/PlanThreeDsLevels" }, { "type": "null" } ] } }, "required": [ "mode", "company_id" ], "title": "CreateCheckoutSessionInputModeSetup", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutConfiguration" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "checkout_configuration:create", "plan:create", "access_pass:create", "access_pass:update", "checkout_configuration:basic:read" ] } ], "summary": "Create checkout configuration", "tags": [ "Checkout configurations" ], "x-group-title": "Payins" } }, "/checkout_configurations/{id}": { "get": { "description": "Retrieves the details of an existing checkout configuration.\n\nRequired permissions:\n - `checkout_configuration:basic:read`", "operationId": "retrieveCheckoutConfiguration", "parameters": [ { "description": "The unique identifier of the checkout configuration.", "in": "path", "name": "id", "required": true, "schema": { "example": "ch_xxxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutConfiguration" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "checkout_configuration:basic:read" ] } ], "summary": "Retrieve checkout configuration", "tags": [ "Checkout configurations" ], "x-group-title": "Payins" } }, "/companies": { "get": { "description": "Returns a paginated list of companies. When parent_company_id is provided, lists connected accounts under that platform. When omitted, lists companies the current user has access to.\n\nRequired permissions:\n - `company:basic:read`", "operationId": "listCompany", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "parent_company_id", "required": false, "schema": { "description": "The unique identifier of the parent platform company. When provided, lists connected accounts under that platform. Omit to list the current user's own companies.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return companies created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return companies created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicCompany.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CompanyListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "List companies", "tags": [ "Companies" ], "x-group-title": "Identity" }, "post": { "description": "Create a new company. Pass parent_company_id to create a connected account under a platform, or omit it to create a company for the current user.\n\nRequired permissions:\n - `company:create`\n - `company:basic:read`", "operationId": "createCompany", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateCompany", "properties": { "description": { "description": "A promotional pitch displayed to potential customers on the company's store page.", "type": [ "string", "null" ] }, "email": { "description": "The email address of the user who will own the connected account. Required when parent_company_id is provided.", "type": [ "string", "null" ] }, "logo": { "description": "The company's logo image. Accepts PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "A key-value JSON object of custom metadata to store on the company.", "type": [ "object", "null" ] }, "parent_company_id": { "description": "The unique identifier of the parent platform company. When provided, creates a connected account under that platform. Omit to create a company for the current user.", "type": [ "string", "null" ] }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this company. Only applies when creating a connected account.", "type": [ "boolean", "null" ] }, "title": { "description": "The display name of the company shown to customers.", "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:create", "company:basic:read" ] } ], "summary": "Create company", "tags": [ "Companies" ], "x-group-title": "Identity" } }, "/companies/{id}": { "get": { "description": "Retrieves the details of an existing company.\n\nRequired permissions:\n - `company:basic:read`", "operationId": "retrieveCompany", "parameters": [ { "description": "The unique identifier or route slug of the company.", "in": "path", "name": "id", "required": true, "schema": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Retrieve company", "tags": [ "Companies" ], "x-group-title": "Identity" }, "patch": { "description": "Update a company's title, description, logo, and other settings.\n\nRequired permissions:\n - `company:update`\n - `company:basic:read`", "operationId": "updateCompany", "parameters": [ { "description": "The unique identifier of the company to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateCompany", "properties": { "affiliate_application_required": { "description": "Whether prospective affiliates must submit an application before they can promote this company.", "type": [ "boolean", "null" ] }, "affiliate_instructions": { "description": "Guidelines and instructions shown to affiliates explaining how to promote this company's products.", "type": [ "string", "null" ] }, "banner_image": { "description": "The company's banner image. Accepts PNG or JPEG format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "description": { "description": "A promotional pitch displayed to potential customers on the company's store page.", "type": [ "string", "null" ] }, "featured_affiliate_product_id": { "description": "The ID of the product to feature on this company's affiliate page. Pass null to clear.", "type": [ "string", "null" ] }, "logo": { "description": "The company's logo image. Accepts PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "route": { "description": "The unique URL slug for the company's store page. Must be lowercase and can include hyphens (e.g., 'my-company'). If not provided, the route will remain unchanged.", "type": [ "string", "null" ] }, "send_customer_emails": { "description": "Whether Whop sends transactional emails (receipts, renewals, cancelations) to customers on behalf of this company.", "type": [ "boolean", "null" ] }, "social_links": { "description": "The social media links to display on the company's store page. Pass the full list of desired social links — any existing links not included will be removed.", "items": { "description": "Input for creating a social link for a company", "properties": { "image": { "description": "The custom image for the social link", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "order": { "description": "The order of the social link", "example": "123.45", "type": [ "string", "null" ] }, "title": { "description": "The title of the social link", "type": [ "string", "null" ] }, "url": { "description": "The URL of the social link", "example": "https://example.com/path", "type": "string" }, "website": { "$ref": "#/components/schemas/SocialLinkWebsites", "description": "The website this link is for" }, "website_order": { "description": "The order of the website social link", "example": "123.45", "type": [ "string", "null" ] } }, "required": [ "url", "website" ], "type": "object" }, "type": [ "array", "null" ] }, "target_audience": { "description": "The target audience for this company (e.g., 'beginner day traders aged 18-25 looking to learn options').", "type": [ "string", "null" ] }, "title": { "description": "The display name of the company shown to customers.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update", "company:basic:read" ] } ], "summary": "Update company", "tags": [ "Companies" ], "x-group-title": "Identity" } }, "/companies/{parent_company_id}/api_keys": { "post": { "description": "Create an API key for a connected account (child company) owned by a parent company.", "operationId": "createApiKeyCompany", "parameters": [ { "description": "The unique identifier of the parent platform company (e.g. 'biz_xxx').", "in": "path", "name": "parent_company_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateChildCompanyApiKey", "properties": { "child_company_id": { "description": "The unique identifier of the connected account to create the API key for (e.g. 'biz_xxx').", "type": "string" }, "name": { "description": "A human-readable name for the API key, such as 'Production API Key'.", "type": [ "string", "null" ] }, "permissions": { "description": "Granular permission statements defining which actions this API key can perform. Either permissions or role must be provided.", "items": { "description": "Input for a single permissions statement", "properties": { "actions": { "description": "Actions covered by this statement", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "grant": { "description": "Whether the actions are granted or denied", "type": "boolean" }, "resources": { "description": "Resource identifiers. Can look like 'biz_xxxx' or 'biz_xxx|pass_*|exp_xxx' or 'biz_xxx|app_xxx' or 'biz_xxx|pass_xxx|exp_xxx' or 'biz_xxx|pass_xxx' or 'biz_xxx|pass_*'", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" } }, "required": [ "actions", "grant", "resources" ], "type": "object" }, "type": [ "array", "null" ] }, "role": { "description": "A system role to inherit permissions from (e.g. owner, admin, moderator). Either role or permissions must be provided.", "oneOf": [ { "$ref": "#/components/schemas/PermissionSystemRoles" }, { "type": "null" } ] } }, "required": [ "child_company_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "An API key created for a child company, including the one-time secret key.", "properties": { "id": { "description": "The unique identifier for the authorized api key.", "type": "string" }, "name": { "description": "A user set name to identify an API key", "type": [ "string", "null" ] }, "secret_key": { "description": "The secret key used to authenticate requests. Only returned at creation time.", "type": "string" } }, "required": [ "id", "name", "secret_key" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create child company API key", "tags": [ "Companies" ], "x-group-title": "Identity" } }, "/company_token_transactions": { "get": { "description": "Returns a paginated list of token transactions for a user or company, depending on the authenticated actor, with optional filtering by user and transaction type.\n\nRequired permissions:\n - `company_token_transaction:read`\n - `member:basic:read`\n - `company:basic:read`", "operationId": "listCompanyTokenTransaction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list token transactions for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter transactions to only those involving this specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "transaction_type", "required": false, "schema": { "description": "Filter transactions by type.", "oneOf": [ { "$ref": "#/components/schemas/CompanyTokenTransactionTypes" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CompanyTokenTransaction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CompanyTokenTransactionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company_token_transaction:read", "member:basic:read", "company:basic:read" ] } ], "summary": "List company token transactions", "tags": [ "Company token transactions" ], "x-group-title": "CRM" }, "post": { "description": "Create a token transaction to add, subtract, or transfer tokens for a member within a company.\n\nRequired permissions:\n - `company_token_transaction:create`\n - `member:basic:read`\n - `company:basic:read`", "operationId": "createCompanyTokenTransaction", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateCompanyTokenTransaction", "oneOf": [ { "description": "Autogenerated input type of CreateCompanyTokenTransaction", "properties": { "amount": { "description": "The positive number of tokens to transact. For example, 100.0 for 100 tokens.", "example": 6.9, "type": "number" }, "company_id": { "description": "The unique identifier of the company to create the transaction in, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "description": { "description": "A human-readable description of why the transaction was created.", "type": [ "string", "null" ] }, "destination_user_id": { "description": "The unique identifier of the user receiving the tokens. Required when the transaction type is 'transfer'.", "type": "string" }, "idempotency_key": { "description": "A unique key to prevent duplicate transactions. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "transaction_type": { "const": "transfer", "type": "string" }, "user_id": { "description": "The unique identifier of the user whose token balance will be affected, starting with 'user_'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "company_id", "transaction_type", "user_id", "destination_user_id" ], "title": "CreateCompanyTokenTransactionInputTransactionTypeTransfer", "type": "object" }, { "description": "Autogenerated input type of CreateCompanyTokenTransaction", "properties": { "amount": { "description": "The positive number of tokens to transact. For example, 100.0 for 100 tokens.", "example": 6.9, "type": "number" }, "company_id": { "description": "The unique identifier of the company to create the transaction in, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "description": { "description": "A human-readable description of why the transaction was created.", "type": [ "string", "null" ] }, "idempotency_key": { "description": "A unique key to prevent duplicate transactions. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "transaction_type": { "const": "add", "type": "string" }, "user_id": { "description": "The unique identifier of the user whose token balance will be affected, starting with 'user_'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "company_id", "transaction_type", "user_id" ], "title": "CreateCompanyTokenTransactionInputTransactionTypeAdd", "type": "object" }, { "description": "Autogenerated input type of CreateCompanyTokenTransaction", "properties": { "amount": { "description": "The positive number of tokens to transact. For example, 100.0 for 100 tokens.", "example": 6.9, "type": "number" }, "company_id": { "description": "The unique identifier of the company to create the transaction in, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "description": { "description": "A human-readable description of why the transaction was created.", "type": [ "string", "null" ] }, "idempotency_key": { "description": "A unique key to prevent duplicate transactions. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "transaction_type": { "const": "subtract", "type": "string" }, "user_id": { "description": "The unique identifier of the user whose token balance will be affected, starting with 'user_'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "company_id", "transaction_type", "user_id" ], "title": "CreateCompanyTokenTransactionInputTransactionTypeSubtract", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyTokenTransaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company_token_transaction:create", "member:basic:read", "company:basic:read" ] } ], "summary": "Create company token transaction", "tags": [ "Company token transactions" ], "x-group-title": "CRM" } }, "/company_token_transactions/{id}": { "get": { "description": "Retrieves the details of an existing company token transaction.\n\nRequired permissions:\n - `company_token_transaction:read`\n - `member:basic:read`\n - `company:basic:read`", "operationId": "retrieveCompanyTokenTransaction", "parameters": [ { "description": "The unique identifier of the token transaction to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyTokenTransaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company_token_transaction:read", "member:basic:read", "company:basic:read" ] } ], "summary": "Retrieve company token transaction", "tags": [ "Company token transactions" ], "x-group-title": "CRM" } }, "/conversions": { "post": { "description": "Track a conversion or engagement event for a company.\n\nRequired permissions:\n - `event:create`", "operationId": "createConversion", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateConversion", "properties": { "action_source": { "description": "Where the event originated.", "oneOf": [ { "$ref": "#/components/schemas/EventActionSource" }, { "type": "null" } ] }, "company_id": { "description": "The company to associate with this event.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "context": { "description": "Tracking and attribution context.", "properties": { "ad_campaign_id": { "description": "Ad campaign ID.", "type": [ "string", "null" ] }, "ad_id": { "description": "Ad ID.", "type": [ "string", "null" ] }, "ad_set_id": { "description": "Ad set ID.", "type": [ "string", "null" ] }, "fbc": { "description": "Facebook click cookie (_fbc, format fb.1.{timestamp}.{fbclid}).", "type": [ "string", "null" ] }, "fbclid": { "description": "Facebook click ID.", "type": [ "string", "null" ] }, "fbp": { "description": "Facebook browser pixel ID.", "type": [ "string", "null" ] }, "fingerprint": { "description": "Client-side device fingerprint.", "type": [ "string", "null" ] }, "fingerprint_confidence": { "description": "Confidence score (0-1) for the device fingerprint.", "example": 6.9, "type": [ "number", "null" ] }, "ga": { "description": "Google Analytics client ID.", "type": [ "string", "null" ] }, "gbraid": { "description": "Google Ads gbraid click ID (iOS privacy).", "type": [ "string", "null" ] }, "gclid": { "description": "Google click ID.", "type": [ "string", "null" ] }, "ig_sid": { "description": "Instagram session ID.", "type": [ "string", "null" ] }, "ip_address": { "description": "IP address.", "type": [ "string", "null" ] }, "language": { "description": "Browser language (e.g. en-US).", "type": [ "string", "null" ] }, "li_fat_id": { "description": "LinkedIn click ID.", "type": [ "string", "null" ] }, "msclkid": { "description": "Microsoft Advertising (Bing) click ID.", "type": [ "string", "null" ] }, "rdt_cid": { "description": "Reddit click ID.", "type": [ "string", "null" ] }, "sccid": { "description": "Snapchat click ID.", "type": [ "string", "null" ] }, "screen_resolution": { "description": "Screen resolution (e.g. 1920x1080).", "type": [ "string", "null" ] }, "timezone": { "description": "IANA timezone (e.g. America/New_York).", "type": [ "string", "null" ] }, "ttclid": { "description": "TikTok click ID.", "type": [ "string", "null" ] }, "ttp": { "description": "TikTok pixel ID.", "type": [ "string", "null" ] }, "twclid": { "description": "X (Twitter) click ID.", "type": [ "string", "null" ] }, "user_agent": { "description": "Browser user agent string.", "type": [ "string", "null" ] }, "utm_campaign": { "description": "UTM campaign parameter.", "type": [ "string", "null" ] }, "utm_content": { "description": "UTM content parameter.", "type": [ "string", "null" ] }, "utm_id": { "description": "UTM ID parameter.", "type": [ "string", "null" ] }, "utm_medium": { "description": "UTM medium parameter.", "type": [ "string", "null" ] }, "utm_source": { "description": "UTM source parameter.", "type": [ "string", "null" ] }, "utm_term": { "description": "UTM term parameter.", "type": [ "string", "null" ] }, "wbraid": { "description": "Google Ads wbraid click ID (iOS privacy).", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "currency": { "description": "ISO 4217 currency code.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "custom_name": { "description": "Custom event name when event_name is 'custom'. Maximum 35 chars for this value.", "type": [ "string", "null" ] }, "duration": { "description": "For 'leave' events: milliseconds the visitor spent on the page.", "example": 42, "type": [ "integer", "null" ] }, "event_id": { "description": "Client-provided identifier for deduplication. Generated if omitted.", "example": "evnt_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "event_name": { "$ref": "#/components/schemas/EventName", "description": "The type of event." }, "event_time": { "description": "When the event occurred. Defaults to now.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "plan_id": { "description": "The plan associated with the event.", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product associated with the event.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "referrer_url": { "description": "The referring URL.", "type": [ "string", "null" ] }, "resumed": { "description": "For 'page' events: true when the page was restored from the back/forward cache.", "type": [ "boolean", "null" ] }, "source": { "description": "For 'identify' events: where the identity was captured (url, form, manual, iframe).", "type": [ "string", "null" ] }, "title": { "description": "For 'page' events: the document title.", "type": [ "string", "null" ] }, "url": { "description": "The URL where the event occurred.", "type": [ "string", "null" ] }, "user": { "description": "User identity and profile data.", "properties": { "anonymous_id": { "description": "An anonymous identifier for the user.", "type": [ "string", "null" ] }, "birthdate": { "description": "Date of birth (YYYY-MM-DD).", "example": "1990-01-15", "type": [ "string", "null" ] }, "city": { "description": "City.", "type": [ "string", "null" ] }, "country": { "description": "Country.", "type": [ "string", "null" ] }, "email": { "description": "Email address.", "type": [ "string", "null" ] }, "external_id": { "description": "An external identifier for the user.", "type": [ "string", "null" ] }, "first_name": { "description": "First name.", "type": [ "string", "null" ] }, "gender": { "description": "Gender.", "oneOf": [ { "$ref": "#/components/schemas/EventGender" }, { "type": "null" } ] }, "last_name": { "description": "Last name.", "type": [ "string", "null" ] }, "linked_anonymous_id": { "description": "A second anonymous identifier to link to this user (e.g. captured across an iframe boundary).", "type": [ "string", "null" ] }, "linked_wuid": { "description": "A wuid from a linked frame, captured across an iframe boundary.", "type": [ "string", "null" ] }, "member_id": { "description": "The Whop member ID.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "membership_id": { "description": "The Whop membership ID.", "example": "mem_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "name": { "description": "Full display name.", "type": [ "string", "null" ] }, "phone": { "description": "Phone number.", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "type": [ "string", "null" ] }, "state": { "description": "State or region.", "type": [ "string", "null" ] }, "user_id": { "description": "The Whop user ID.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "Username.", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "value": { "description": "Monetary value associated with the event.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "company_id", "event_name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A tracked conversion event", "properties": { "id": { "description": "The unique identifier for the conversion", "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "event:create" ] } ], "summary": "Create conversion", "tags": [ "Conversions" ], "x-group-title": "Ads" } }, "/course_chapters": { "get": { "description": "Returns a paginated list of chapters within a course, ordered by position.\n\nRequired permissions:\n - `courses:read`", "operationId": "listCourseChapter", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": true, "schema": { "description": "The unique identifier of the course to list chapters for.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Chapter.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseChapterListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "List course chapters", "tags": [ "Course chapters" ], "x-group-title": "Courses" }, "post": { "description": "Create a new chapter within a course to organize lessons into sections.\n\nRequired permissions:\n - `courses:update`", "operationId": "createCourseChapter", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateChapter", "properties": { "course_id": { "description": "The unique identifier of the course to create the chapter in (e.g., \"course_XXXXX\").", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display title of the chapter (e.g., \"Module 1: Introduction\").", "type": [ "string", "null" ] } }, "required": [ "course_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseChapter" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Create course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" } }, "/course_chapters/{id}": { "delete": { "description": "Permanently delete a chapter and all of its lessons from a course.\n\nRequired permissions:\n - `courses:update`", "operationId": "deleteCourseChapter", "parameters": [ { "description": "The unique identifier of the chapter to delete (e.g., \"chap_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "chap_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Delete course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" }, "get": { "description": "Retrieves the details of an existing course chapter.\n\nRequired permissions:\n - `courses:read`", "operationId": "retrieveCourseChapter", "parameters": [ { "description": "The unique identifier of the chapter to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "chap_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseChapter" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "Retrieve course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" }, "patch": { "description": "Update a chapter's title within a course.\n\nRequired permissions:\n - `courses:update`", "operationId": "updateCourseChapter", "parameters": [ { "description": "The unique identifier of the chapter to update (e.g., \"chap_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "chap_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateChapter", "properties": { "title": { "description": "The new display title of the chapter (e.g., \"Module 1: Introduction\").", "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseChapter" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Update course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" } }, "/course_lesson_interactions": { "get": { "description": "Returns a paginated list of lesson interactions, filtered by lesson, course, user, or completion status.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "listCourseLessonInteraction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "The unique identifier of the user to filter lesson interactions for.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "lesson_id", "required": false, "schema": { "description": "The unique identifier of the lesson to filter interactions for.", "example": "lesn_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": false, "schema": { "description": "The unique identifier of the course to filter interactions for.", "example": "cors_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "completed", "required": false, "schema": { "description": "Whether to filter for completed or in-progress lesson interactions.", "type": [ "boolean", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for LessonInteraction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseLessonInteractionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "List course lesson interactions", "tags": [ "Course lesson interactions" ], "x-group-title": "Courses" } }, "/course_lesson_interactions/{id}": { "get": { "description": "Retrieves the details of an existing course lesson interaction.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "retrieveCourseLessonInteraction", "parameters": [ { "description": "The unique identifier of the lesson interaction to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "crsli_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLessonInteraction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "Retrieve course lesson interaction", "tags": [ "Course lesson interactions" ], "x-group-title": "Courses" } }, "/course_lessons": { "get": { "description": "Returns a paginated list of lessons within a course or chapter, ordered by position.\n\nRequired permissions:\n - `courses:read`", "operationId": "listCourseLesson", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": false, "schema": { "description": "The unique identifier of the course to return all lessons across all chapters.", "example": "cors_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "chapter_id", "required": false, "schema": { "description": "The unique identifier of a chapter to return only its lessons.", "example": "chap_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Lesson.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseLessonListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "List course lessons", "tags": [ "Course lessons" ], "x-group-title": "Courses" }, "post": { "description": "Create a new lesson within a course chapter. Lessons can contain video, text, or assessment content.\n\nRequired permissions:\n - `courses:update`", "operationId": "createCourseLesson", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateLesson", "properties": { "chapter_id": { "description": "The unique identifier of the chapter to create the lesson in (e.g., \"chap_XXXXX\").", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "content": { "description": "The Markdown content body of the lesson.", "type": [ "string", "null" ] }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded content (e.g., a YouTube video ID or Loom share ID).", "type": [ "string", "null" ] }, "embed_type": { "description": "The type of video embed for this lesson, such as YouTube or Loom.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content type of the lesson, such as video, text, quiz, or knowledge check." }, "thumbnail": { "description": "The thumbnail image for the lesson in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the lesson (e.g., \"Getting Started with APIs\").", "type": [ "string", "null" ] } }, "required": [ "chapter_id", "lesson_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLesson" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Create course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{id}": { "delete": { "description": "Permanently delete a lesson and remove it from its chapter.\n\nRequired permissions:\n - `courses:update`", "operationId": "deleteCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to delete (e.g., \"les_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "lesn_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Delete course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" }, "get": { "description": "Retrieves the details of an existing course lesson.\n\nRequired permissions:\n - `courses:read`", "operationId": "retrieveCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "lesn_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLesson" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "Retrieve course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" }, "patch": { "description": "Update a lesson's content, type, visibility, assessment questions, or media attachments.\n\nRequired permissions:\n - `courses:update`", "operationId": "updateCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to update (e.g., \"les_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "lesn_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateLesson", "properties": { "assessment_completion_requirement": { "description": "The passing criteria for quiz or knowledge check lessons, such as minimum grade or correct answers.", "properties": { "minimum_grade_percent": { "description": "The minimum grade percentage required to pass (0-100). Cannot be set together with minimum_questions_correct.", "example": 6.9, "type": [ "number", "null" ] }, "minimum_questions_correct": { "description": "The minimum number of questions that must be answered correctly. Cannot be set together with minimum_grade_percent.", "example": 42, "type": [ "integer", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "assessment_questions": { "description": "The full list of assessment questions for quiz or knowledge check lessons. Replaces all existing questions.", "items": { "description": "Input for creating or updating an assessment question", "properties": { "correct_answer": { "description": "The correct answer for the question. Used for short answer questions", "type": "string" }, "id": { "description": "The ID of an existing question. If provided, the question will be updated. If not provided, a new question will be created.", "type": [ "string", "null" ] }, "image": { "description": "Optional image attachment for the question", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "options": { "description": "The answer options for multiple choice/select questions", "items": { "description": "Input for creating or updating an assessment question option", "properties": { "id": { "description": "The ID of an existing option. If provided, the option will be updated. If not provided, a new option will be created.", "type": [ "string", "null" ] }, "is_correct": { "description": "Whether this option is a correct answer", "type": "boolean" }, "option_text": { "description": "The text of the answer option", "type": "string" } }, "required": [ "is_correct", "option_text" ], "type": "object" }, "type": [ "array", "null" ] }, "question_text": { "description": "The text of the question", "type": "string" }, "question_type": { "$ref": "#/components/schemas/CoursesAssessmentQuestionTypes", "description": "The type of the question" } }, "required": [ "correct_answer", "question_text", "question_type" ], "type": "object" }, "type": [ "array", "null" ] }, "attachments": { "description": "File attachments for the lesson such as PDFs or documents. Replaces all existing attachments.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The Markdown content body of the lesson.", "type": [ "string", "null" ] }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded content (e.g., a YouTube video ID or Loom share ID).", "type": [ "string", "null" ] }, "embed_type": { "description": "The type of video embed for this lesson, such as YouTube or Loom.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "lesson_type": { "description": "The content type of the lesson, such as video, text, quiz, or knowledge check.", "oneOf": [ { "$ref": "#/components/schemas/LessonTypes" }, { "type": "null" } ] }, "main_pdf": { "description": "The primary PDF document attached to this lesson for student reference.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "max_attempts": { "description": "The maximum number of attempts a student is allowed for assessment lessons.", "example": 42, "type": [ "integer", "null" ] }, "mux_asset_id": { "description": "The identifier of a Mux video asset to attach to this lesson (e.g., \"mux_XXXXX\").", "example": "mux_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image for the lesson in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the lesson (e.g., \"Getting Started with APIs\").", "type": [ "string", "null" ] }, "visibility": { "description": "Controls whether this lesson is visible to students or hidden as a draft.", "oneOf": [ { "$ref": "#/components/schemas/LessonVisibilities" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLesson" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Update course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{lesson_id}/mark_as_completed": { "post": { "description": "Mark a lesson as completed for the current user after they finish the content.", "operationId": "markAsCompletedCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to mark as completed (e.g., \"les_XXXXX\").", "in": "path", "name": "lesson_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Mark as completed course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{lesson_id}/start": { "post": { "description": "Record that the current user has started viewing a lesson, creating progress tracking records.", "operationId": "startCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson the user is starting (e.g., \"les_XXXXX\").", "in": "path", "name": "lesson_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Start course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{lesson_id}/submit_assessment": { "post": { "description": "Submit answers for a quiz or knowledge check lesson and receive a graded result.", "operationId": "submitAssessmentCourseLesson", "parameters": [ { "description": "The unique identifier of the quiz or knowledge check lesson to submit answers for (e.g., \"les_XXXXX\").", "in": "path", "name": "lesson_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for SubmitAssessment", "properties": { "answers": { "description": "The list of answers to submit for each assessment question.", "items": { "description": "Input for a single question's answer in an assessment submission", "properties": { "answer_text": { "description": "The text answer provided by the user (for short answer questions)", "type": [ "string", "null" ] }, "question_id": { "description": "The ID of the question being answered", "type": "string" }, "selected_option_ids": { "description": "The IDs of the selected options (for multiple choice/select questions)", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "question_id" ], "type": "object" }, "type": "array" } }, "required": [ "answers" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The result of a user's assessment attempt", "properties": { "created_at": { "description": "The datetime the assessment result was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the assessment result.", "example": "crsar_xxxxxxxxxxxx", "type": "string" }, "lesson": { "description": "The lesson this assessment result is for", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "result_correct": { "description": "The number of correct answers", "example": 42, "type": "integer" }, "result_grade": { "description": "The grade achieved on the assessment", "example": 6.9, "type": "number" }, "result_graded_questions": { "additionalProperties": true, "description": "Array of graded questions with details", "type": "object" }, "result_passing_grade": { "description": "Whether the user achieved a passing grade", "type": "boolean" }, "result_question_count": { "description": "The total number of questions in the assessment", "example": 42, "type": "integer" }, "score_percent": { "description": "The percentage score achieved on the assessment", "example": 6.9, "type": "number" }, "updated_at": { "description": "The datetime the assessment result was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who took the assessment", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "created_at", "updated_at", "result_grade", "result_correct", "result_question_count", "result_passing_grade", "result_graded_questions", "score_percent", "user", "lesson" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Submit assessment course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_students": { "get": { "description": "Returns a paginated list of students enrolled in a course, with optional name filtering.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "listCourseStudent", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": true, "schema": { "description": "The unique identifier of the course to list enrolled students for.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "keyword", "required": false, "schema": { "description": "A search term to filter students by name or username.", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CourseStudentType.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseStudentListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "List course students", "tags": [ "Course students" ], "x-group-title": "Courses" } }, "/course_students/{id}": { "get": { "description": "Retrieves the details of an existing course student.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "retrieveCourseStudent", "parameters": [ { "description": "The unique identifier of the course student record to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseStudent" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "Retrieve course student", "tags": [ "Course students" ], "x-group-title": "Courses" } }, "/courses": { "get": { "description": "Returns a paginated list of courses, filtered by either an experience or a company.\n\nRequired permissions:\n - `courses:read`", "operationId": "listCourse", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "experience_id", "required": false, "schema": { "description": "The unique identifier of the experience to list courses for.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list courses for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Course.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "List courses", "tags": [ "Courses" ], "x-group-title": "Courses" }, "post": { "description": "Create a new course within an experience, with optional chapters, lessons, and a certificate.\n\nRequired permissions:\n - `courses:update`", "operationId": "createCourse", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateCourse", "properties": { "certificate_after_completion_enabled": { "description": "Whether the course awards students a PDF certificate after completing all lessons.", "type": [ "boolean", "null" ] }, "experience_id": { "description": "The unique identifier of the experience to create the course in (e.g., \"exp_XXXXX\").", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "order": { "description": "The decimal order position of the course within its experience. Use fractional values (e.g., \"1.5\") to place between existing courses.", "example": "123.45", "type": [ "string", "null" ] }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": [ "boolean", "null" ] }, "tagline": { "description": "A short tagline displayed beneath the course title (e.g., \"Master the fundamentals of design\").", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image for the course in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the course (e.g., \"Introduction to Web Development\").", "type": "string" }, "visibility": { "description": "Controls whether this course is visible to students or hidden as a draft.", "oneOf": [ { "$ref": "#/components/schemas/CourseVisibilities" }, { "type": "null" } ] } }, "required": [ "experience_id", "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Course" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Create course", "tags": [ "Courses" ], "x-group-title": "Courses" } }, "/courses/{id}": { "delete": { "description": "Permanently delete a course and all of its chapters, lessons, and student progress.\n\nRequired permissions:\n - `courses:update`", "operationId": "deleteCourse", "parameters": [ { "description": "The unique identifier of the course to delete (e.g., \"course_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "cors_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Delete course", "tags": [ "Courses" ], "x-group-title": "Courses" }, "get": { "description": "Retrieves the details of an existing course.\n\nRequired permissions:\n - `courses:read`", "operationId": "retrieveCourse", "parameters": [ { "description": "The unique identifier of the course to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "cors_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Course" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "Retrieve course", "tags": [ "Courses" ], "x-group-title": "Courses" }, "patch": { "description": "Update a course's title, description, visibility, thumbnail, or chapter ordering.\n\nRequired permissions:\n - `courses:update`", "operationId": "updateCourse", "parameters": [ { "description": "The unique identifier of the course to update (e.g., \"course_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "cors_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateCourse", "properties": { "certificate_after_completion_enabled": { "description": "Whether the course awards students a PDF certificate after completing all lessons.", "type": [ "boolean", "null" ] }, "chapters": { "description": "A list of chapters with nested lessons to reorder or rename in bulk.", "items": { "description": "Input for updating a chapter while updating a course", "properties": { "id": { "description": "The ID of the chapter to update", "type": "string" }, "lessons": { "description": "The lessons to update within this chapter", "items": { "description": "Input for updating a lesson while updating a course", "properties": { "chapter_id": { "description": "The ID of the chapter this lesson belongs to (for moving between chapters)", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of the lesson to update", "type": "string" }, "order": { "description": "The order of the lesson within its chapter", "example": 42, "type": "integer" }, "title": { "description": "The title of the lesson", "type": "string" } }, "required": [ "chapter_id", "id", "order", "title" ], "type": "object" }, "type": [ "array", "null" ] }, "order": { "description": "The order of the chapter within its course", "example": 42, "type": "integer" }, "title": { "description": "The title of the chapter", "type": "string" } }, "required": [ "id", "order", "title" ], "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A short description of the course displayed to students on the course page.", "type": [ "string", "null" ] }, "language": { "description": "The primary language spoken in the video content of the course.", "oneOf": [ { "$ref": "#/components/schemas/Languages" }, { "type": "null" } ] }, "order": { "description": "The decimal order position of the course within its experience. Use fractional values (e.g., \"1.5\") to place between existing courses.", "example": "123.45", "type": [ "string", "null" ] }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": [ "boolean", "null" ] }, "tagline": { "description": "A short tagline displayed beneath the course title (e.g., \"Master the fundamentals of design\").", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image for the course in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the course (e.g., \"Introduction to Web Development\").", "type": [ "string", "null" ] }, "visibility": { "description": "Controls whether this course is visible to students or hidden as a draft.", "oneOf": [ { "$ref": "#/components/schemas/CourseVisibilities" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Course" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Update course", "tags": [ "Courses" ], "x-group-title": "Courses" } }, "/deposits": { "post": { "description": "Resolves a deposit destination and returns the on-chain addresses that can fund it.", "operationId": "createDeposit", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Amount to deposit.", "type": "number" }, "destination": { "description": "Destination account ID or wallet address. Object form is supported for compatibility.", "oneOf": [ { "type": "string" }, { "properties": { "account_id": { "type": "string" }, "address": { "type": "string" }, "network": { "type": "string" } }, "type": "object" } ] }, "metadata": { "additionalProperties": true, "description": "Arbitrary metadata echoed in the response.", "type": "object" }, "network": { "description": "Optional destination network override.", "nullable": true, "type": "string" } }, "required": [ "amount", "destination" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "amount": { "type": "string" }, "deposit_address": { "properties": { "evm": { "type": "string" }, "solana": { "type": "string" } }, "required": [ "evm", "solana" ], "type": "object" }, "destination": { "properties": { "account_id": { "nullable": true, "type": "string" }, "address": { "type": "string" }, "currency": { "type": "string" }, "network": { "type": "string" } }, "required": [ "address", "network", "currency" ], "type": "object" }, "hosted_url": { "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "object": { "enum": [ "deposit" ], "type": "string" } }, "required": [ "object", "amount", "destination", "deposit_address", "hosted_url", "metadata" ], "type": "object" } } }, "description": "deposit created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the charge scope" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create Deposit", "tags": [ "Deposits" ] } }, "/dispute_alerts": { "get": { "description": "Returns a paginated list of dispute alerts for a company, with optional filtering by creation date.\n\nRequired permissions:\n - `payment:dispute_alert:read`\n - `payment:basic:read`\n - `payment:dispute:read`", "operationId": "listDisputeAlert", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list dispute alerts for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return dispute alerts created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return dispute alerts created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DisputeAlert.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/DisputeAlertListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:dispute_alert:read", "payment:basic:read", "payment:dispute:read" ] } ], "summary": "List dispute alerts", "tags": [ "Dispute alerts" ], "x-group-title": "Payins" } }, "/dispute_alerts/{id}": { "get": { "description": "Retrieves the details of an existing dispute alert.\n\nRequired permissions:\n - `payment:dispute_alert:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `payment:dispute:read`", "operationId": "retrieveDisputeAlert", "parameters": [ { "description": "The unique identifier of the dispute alert.", "in": "path", "name": "id", "required": true, "schema": { "example": "dspa_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeAlert" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:dispute_alert:read", "payment:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "payment:dispute:read" ] } ], "summary": "Retrieve dispute alert", "tags": [ "Dispute alerts" ], "x-group-title": "Payins" } }, "/disputes": { "get": { "description": "Returns a paginated list of disputes for a company, with optional filtering by creation date. A dispute represents a chargeback or inquiry filed by a customer against a payment.\n\nRequired permissions:\n - `payment:dispute:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`", "operationId": "listDispute", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list disputes for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return disputes created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return disputes created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Dispute.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/DisputeListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:dispute:read", "plan:basic:read", "access_pass:basic:read", "company:basic:read", "payment:basic:read" ] } ], "summary": "List disputes", "tags": [ "Disputes" ], "x-group-title": "Payins" } }, "/disputes/{id}": { "get": { "description": "Retrieves the details of an existing dispute.\n\nRequired permissions:\n - `payment:dispute:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`", "operationId": "retrieveDispute", "parameters": [ { "description": "The unique identifier of the dispute.", "in": "path", "name": "id", "required": true, "schema": { "example": "dspt_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:dispute:read", "plan:basic:read", "access_pass:basic:read", "company:basic:read", "payment:basic:read", "member:email:read", "member:basic:read", "member:phone:read" ] } ], "summary": "Retrieve dispute", "tags": [ "Disputes" ], "x-group-title": "Payins" } }, "/disputes/{id}/submit_evidence": { "post": { "description": "Submit a payment dispute to the payment processor for review. Once submitted, no further edits can be made.\n\nRequired permissions:\n - `payment:dispute`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`", "operationId": "submitEvidenceDispute", "parameters": [ { "description": "The unique identifier of the dispute to submit to the payment processor for review.", "in": "path", "name": "id", "required": true, "schema": { "example": "dspt_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:dispute", "plan:basic:read", "access_pass:basic:read", "company:basic:read", "payment:basic:read", "member:email:read", "member:basic:read", "member:phone:read" ] } ], "summary": "Submit evidence", "tags": [ "Disputes" ], "x-group-title": "Payins" } }, "/disputes/{id}/update_evidence": { "post": { "description": "Update a dispute with evidence data to attempt to win the dispute.\n\nRequired permissions:\n - `payment:dispute`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`", "operationId": "updateEvidenceDispute", "parameters": [ { "description": "The unique identifier of the dispute to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "dspt_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateDispute", "properties": { "access_activity_log": { "description": "An IP access activity log showing the customer used the service.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address associated with the customer's payment method.", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "A file upload containing the company's cancellation policy document.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "cancellation_policy_disclosure": { "description": "The company's cancellation policy text to submit as evidence.", "type": [ "string", "null" ] }, "customer_communication_attachment": { "description": "A file upload containing evidence of customer communication. Must be a JPEG, PNG, GIF, or PDF.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "customer_email_address": { "description": "The email address of the customer associated with the disputed payment.", "type": [ "string", "null" ] }, "customer_name": { "description": "The full name of the customer associated with the disputed payment.", "type": [ "string", "null" ] }, "notes": { "description": "Additional notes or context to submit as part of the dispute evidence.", "type": [ "string", "null" ] }, "product_description": { "description": "A description of the product or service that was provided to the customer.", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "A file upload containing the company's refund policy document.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "refund_policy_disclosure": { "description": "The company's refund policy text to submit as evidence.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "An explanation of why the refund request was refused.", "type": [ "string", "null" ] }, "service_date": { "description": "The date when the product or service was delivered to the customer.", "type": [ "string", "null" ] }, "uncategorized_attachment": { "description": "A file upload for evidence that does not fit into the other categories.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:dispute", "plan:basic:read", "access_pass:basic:read", "company:basic:read", "payment:basic:read", "member:email:read", "member:basic:read", "member:phone:read" ] } ], "summary": "Update evidence", "tags": [ "Disputes" ], "x-group-title": "Payins" } }, "/dm_channels": { "get": { "description": "Returns a paginated list of DM channels for the currently authenticated user, sorted by most recently active.\n\nRequired permissions:\n - `dms:read`", "operationId": "listDmChannel", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of a company to filter DM channels by. Only returns channels scoped to this company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/DmChannelListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "List dm channels", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "post": { "description": "Create a new DM channel between two or more users, optionally scoped to a specific company. Returns the existing channel if one already exists.", "operationId": "createDmChannel", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateDmChannelV2", "properties": { "company_id": { "description": "The unique identifier of the company to scope this DM channel to. When set, the channel is visible only within that company context.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "custom_name": { "description": "A custom display name for the DM channel. For example, 'Project Discussion'.", "type": [ "string", "null" ] }, "with_user_ids": { "description": "The list of user identifiers to include in the DM channel. Each entry can be an email, username, or user ID (e.g. 'user_xxxxx').", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" } }, "required": [ "with_user_ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" } }, "/dm_channels/{id}": { "delete": { "description": "Permanently delete a DM channel and all of its messages. Only an admin of the channel can perform this action.\n\nRequired permissions:\n - `dms:channel:manage`", "operationId": "deleteDmChannel", "parameters": [ { "description": "The unique identifier of the DM channel to delete.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] } ], "summary": "Delete dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing DM channel.\n\nRequired permissions:\n - `dms:read`", "operationId": "retrieveDmChannel", "parameters": [ { "description": "The unique identifier of the DM channel to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "Retrieve dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "patch": { "description": "Update the settings of an existing DM channel, such as its display name. Only an admin of the channel can perform this action.\n\nRequired permissions:\n - `dms:channel:manage`", "operationId": "updateDmChannel", "parameters": [ { "description": "The unique identifier of the DM channel to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateDmChannel", "properties": { "custom_name": { "description": "A new custom display name for the DM channel. For example, 'Project Discussion'.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] } ], "summary": "Update dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" } }, "/dm_members": { "get": { "description": "Returns a paginated list of members in a specific DM channel, sorted by the date they were added.\n\nRequired permissions:\n - `dms:read`", "operationId": "listDmMember", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "channel_id", "required": true, "schema": { "description": "The unique identifier of the DM channel to list members for.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsFeedMember.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/DmMemberListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "List dm members", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "post": { "description": "Add a new user to an existing DM channel. Only an admin of the channel can add members.\n\nRequired permissions:\n - `dms:channel:manage`", "operationId": "createDmMember", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateDmMember", "properties": { "channel_id": { "description": "The unique identifier of the DM channel to add the new member to.", "type": "string" }, "user_id": { "description": "The unique identifier of the user to add to the DM channel. For example, 'user_xxxxx'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "channel_id", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmMember" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] } ], "summary": "Create dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" } }, "/dm_members/{id}": { "delete": { "description": "Remove a user from a DM channel. An admin can remove any member, and a member can remove themselves.\n\nRequired permissions:\n - `dms:channel:manage`", "operationId": "deleteDmMember", "parameters": [ { "description": "The unique identifier of the DM channel member to remove.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] } ], "summary": "Delete dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing DM member.\n\nRequired permissions:\n - `dms:read`", "operationId": "retrieveDmMember", "parameters": [ { "description": "The unique identifier of the DM channel member to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmMember" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "Retrieve dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "patch": { "description": "Update a DM channel member's settings, such as their notification preferences or membership status.\n\nRequired permissions:\n - `dms:channel:manage`", "operationId": "updateDmMember", "parameters": [ { "description": "The unique identifier of the DM channel member to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateDmMember", "properties": { "notification_preference": { "description": "The notification setting for this member, controlling how they receive alerts for new messages in this channel.", "oneOf": [ { "$ref": "#/components/schemas/DmsFeedMemberNotificationPreferences" }, { "type": "null" } ] }, "status": { "description": "The membership status for this member in the DM channel.", "oneOf": [ { "$ref": "#/components/schemas/DmsFeedMemberStatuses" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmMember" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] } ], "summary": "Update dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" } }, "/entries": { "get": { "description": "Returns a paginated list of waitlist entries for a company, with optional filtering by product, plan, status, and creation date.\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`", "operationId": "listEntry", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list waitlist entries for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The column to sort waitlist entries by. Defaults to creation date.", "oneOf": [ { "$ref": "#/components/schemas/EntriesSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter entries to only those for specific products.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "plan_ids", "required": false, "schema": { "description": "Filter entries to only those for specific plans.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "statuses", "required": false, "schema": { "description": "Filter entries by their current status.", "items": { "$ref": "#/components/schemas/EntryStatus" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return entries created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return entries created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicEntry.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/EntryListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "plan:waitlist:read", "member:email:read" ] } ], "summary": "List entries", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "/entries/{id}": { "get": { "description": "Retrieves the details of an existing waitlist entry.\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`", "operationId": "retrieveEntry", "parameters": [ { "description": "The unique identifier of the waitlist entry to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "entry_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "plan:waitlist:read", "member:email:read" ] } ], "summary": "Retrieve entry", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "/entries/{id}/approve": { "post": { "description": "Approve a pending waitlist entry, triggering the checkout process to grant the user access to the plan.\n\nRequired permissions:\n - `plan:waitlist:manage`", "operationId": "approveEntry", "parameters": [ { "description": "The unique identifier of the waitlist entry to approve.", "in": "path", "name": "id", "required": true, "schema": { "example": "entry_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "An object representing an asynchronous job.", "properties": { "job_id": { "description": "The ID of the job.", "type": "string" } }, "required": [ "job_id" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "plan:waitlist:manage" ] } ], "summary": "Approve entry", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "/entries/{id}/deny": { "post": { "description": "Deny a pending waitlist entry, preventing the user from gaining access to the plan.\n\nRequired permissions:\n - `plan:waitlist:manage`\n - `plan:basic:read`\n - `member:email:read`", "operationId": "denyEntry", "parameters": [ { "description": "The unique identifier of the waitlist entry to deny.", "in": "path", "name": "id", "required": true, "schema": { "example": "entry_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "plan:waitlist:manage", "plan:basic:read", "member:email:read" ] } ], "summary": "Deny entry", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "/experiences": { "get": { "description": "Returns a paginated list of experiences belonging to a company, with optional filtering by product and app.", "operationId": "listExperience", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list experiences for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": false, "schema": { "description": "Filter to only experiences attached to this product identifier.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "app_id", "required": false, "schema": { "description": "Filter to only experiences powered by this app identifier.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return experiences created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return experiences created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicExperience.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ExperienceListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List experiences", "tags": [ "Experiences" ], "x-group-title": "Engagement" }, "post": { "description": "Required permissions:\n - `experience:create`", "operationId": "createExperience", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateExperience", "properties": { "app_id": { "description": "The unique identifier of the app that powers this experience.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "company_id": { "description": "The unique identifier of the company to create this experience for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "is_public": { "description": "Whether the experience is publicly accessible without a membership.", "type": [ "boolean", "null" ] }, "logo": { "description": "A logo image displayed alongside the experience name.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "name": { "description": "The display name of the experience. Defaults to the app's name if not provided.", "type": [ "string", "null" ] }, "section_id": { "description": "The unique identifier of the section to place the experience in.", "type": [ "string", "null" ] } }, "required": [ "app_id", "company_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:create" ] } ], "summary": "Create experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}": { "delete": { "description": "Required permissions:\n - `experience:delete`", "operationId": "deleteExperience", "parameters": [ { "description": "The unique identifier of the experience to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:delete" ] } ], "summary": "Delete experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing experience.", "operationId": "retrieveExperience", "parameters": [ { "description": "The unique identifier of the experience.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" }, "patch": { "description": "Required permissions:\n - `experience:update`", "operationId": "updateExperience", "parameters": [ { "description": "The unique identifier of the experience to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateExperience", "properties": { "access_level": { "description": "The access level of the experience.", "oneOf": [ { "$ref": "#/components/schemas/ExperienceAccessLevels" }, { "type": "null" } ] }, "is_public": { "description": "Whether the experience is publicly accessible without a membership.", "type": [ "boolean", "null" ] }, "logo": { "description": "A logo image displayed alongside the experience name.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "name": { "description": "The display name of the experience.", "type": [ "string", "null" ] }, "order": { "description": "The position of the experience within its section for display ordering.", "example": "123.45", "type": [ "string", "null" ] }, "section_id": { "description": "The unique identifier of the section to move the experience into.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:update" ] } ], "summary": "Update experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}/attach": { "post": { "description": "Attach an experience to a product, making it accessible to the product's customers.\n\nRequired permissions:\n - `experience:attach`", "operationId": "attachExperience", "parameters": [ { "description": "The unique identifier of the experience to attach.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for AddExperienceToAccessPass", "properties": { "product_id": { "description": "The unique identifier of the product to attach the experience to.", "example": "prod_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "product_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:attach" ] } ], "summary": "Attach experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}/detach": { "post": { "description": "Detach an experience from a product, removing customer access to it through that product.\n\nRequired permissions:\n - `experience:detach`", "operationId": "detachExperience", "parameters": [ { "description": "The unique identifier of the experience to detach.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for RemoveExperienceFromAccessPass", "properties": { "product_id": { "description": "The unique identifier of the product to detach the experience from.", "example": "prod_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "product_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:detach" ] } ], "summary": "Detach experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}/duplicate": { "post": { "description": "Duplicates an existing experience. The name will be copied, unless provided. The new experience will be attached to the same products as the original experience.\nIf duplicating a Forum or Chat experience, the new experience will have the same settings as the original experience, e.g. who can post, who can comment, etc.\nNo content, e.g. posts, messages, lessons from within the original experience will be copied.\n\n\nRequired permissions:\n - `experience:create`", "operationId": "duplicateExperience", "parameters": [ { "description": "The unique identifier of the experience to duplicate.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for DuplicateExperience", "properties": { "name": { "description": "The display name for the duplicated experience. Defaults to the original experience's name.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:create" ] } ], "summary": "Duplicate experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/fee_markups": { "get": { "description": "Returns a paginated list of fee markups configured for a company. If the company is a platform account, returns the platform default markups.\n\nRequired permissions:\n - `company:update_child_fees`", "operationId": "listFeeMarkup", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list fee markups for. Pass a platform account identifier to retrieve platform default markups.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for FeeMarkup.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/FeeMarkupListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "List fee markups", "tags": [ "Fee markups" ], "x-group-title": "Identity" }, "post": { "description": "Create or update a fee markup for a company. If a markup for the specified fee type already exists, it will be updated with the new values.\n\nRequired permissions:\n - `company:update_child_fees`", "operationId": "createFeeMarkup", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateFeeMarkup", "properties": { "company_id": { "description": "The unique identifier of the company to create or update the fee markup for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "fee_type": { "$ref": "#/components/schemas/FeeMarkupTypes", "description": "The type of fee this markup applies to, such as processing or platform fees." }, "fixed_fee_usd": { "description": "The fixed fee amount in USD to charge per transaction. Must be between 0 and 50.", "example": 6.9, "type": [ "number", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value metadata to attach to this fee markup.", "type": [ "object", "null" ] }, "notes": { "description": "Internal notes about this fee markup for record-keeping purposes.", "type": [ "string", "null" ] }, "percentage_fee": { "description": "The percentage fee to charge per transaction. Must be between 0 and 25.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "company_id", "fee_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeMarkup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "Create fee markup", "tags": [ "Fee markups" ], "x-group-title": "Identity" } }, "/fee_markups/{id}": { "delete": { "description": "Delete a fee markup configuration for a company. This removes the custom fee override and reverts to the parent company's default fees.\n\nRequired permissions:\n - `company:update_child_fees`", "operationId": "deleteFeeMarkup", "parameters": [ { "description": "The unique identifier of the fee markup to delete.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "Delete fee markup", "tags": [ "Fee markups" ], "x-group-title": "Identity" } }, "/files": { "post": { "description": "Create a new file record and receive a presigned URL for uploading content to S3.", "operationId": "createFile", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateFile", "properties": { "filename": { "description": "The name of the file including its extension (e.g., \"photo.png\" or \"document.pdf\").", "type": "string" }, "visibility": { "description": "Controls whether the file is publicly accessible via CDN or requires authentication. Defaults to public.", "oneOf": [ { "$ref": "#/components/schemas/FileVisibility" }, { "type": "null" } ] } }, "required": [ "filename" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A file that has been uploaded or is pending upload.", "properties": { "content_type": { "description": "The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded file, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the file.", "example": "file_xxxxxxxxxxxxx", "type": "string" }, "size": { "description": "The file size in bytes. Null if the file has not finished uploading.", "example": "123.45", "type": [ "string", "null" ] }, "upload_headers": { "additionalProperties": true, "description": "Headers to include in the upload request. Only present in the response from the create mutation.", "type": [ "object", "null" ] }, "upload_status": { "$ref": "#/components/schemas/UploadStatuses", "description": "The current upload status of the file (e.g., pending, ready)." }, "upload_url": { "description": "The presigned URL to upload the file contents to. Only present in the response from the create mutation.", "example": "https://media.whop.com/uploads/presigned", "type": [ "string", "null" ] }, "url": { "description": "The URL for accessing the file. For public files, this is a permanent CDN URL. For private files, this is a signed URL that expires. Null if the file has not finished uploading.", "type": [ "string", "null" ] }, "visibility": { "$ref": "#/components/schemas/FileVisibility", "description": "Whether the file is publicly accessible or requires authentication." } }, "required": [ "id", "upload_status", "filename", "content_type", "size", "url", "visibility", "upload_url", "upload_headers" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create file", "tags": [ "Files" ], "x-group-title": "Developer" } }, "/files/{id}": { "get": { "description": "Retrieves the details of an existing file.", "operationId": "retrieveFile", "parameters": [ { "description": "The unique identifier of the file to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "file_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve file", "tags": [ "Files" ], "x-group-title": "Developer" } }, "/financial-activity": { "get": { "description": "Lists financial activity rows for a ledger account. Rows are derived from ledger lines and include typed resource and source objects that clients can use for presentation and navigation. The ledger's owner is passed as exactly one of account_id (a biz_ identifier) or user_id (a user_ identifier).", "operationId": "listFinancialActivity", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional ledger line categories to include.", "explode": true, "in": "query", "name": "line_types", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Optional currency code filter, for example usd.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only include rows posted after this ISO 8601 timestamp.", "in": "query", "name": "posted_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include rows posted before this ISO 8601 timestamp.", "in": "query", "name": "posted_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Maximum number of rows to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor returned by the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "amount": { "description": "Signed amount in the currency's smallest precision units.", "type": "string" }, "created_at": { "format": "date-time", "nullable": true, "type": "string" }, "currency": { "properties": { "code": { "type": "string" }, "precision": { "description": "Precision factor for the currency, for example 100000000 for USD.", "type": "string" } }, "required": [ "code", "precision" ], "type": "object" }, "id": { "type": "string" }, "line_type": { "type": "string" }, "object": { "enum": [ "ledger_activity" ], "type": "string" }, "posted_at": { "format": "date-time", "type": "string" }, "resource": { "oneOf": [ { "properties": { "id": { "type": "string" }, "logo_url": { "nullable": true, "type": "string" }, "object": { "enum": [ "account" ], "type": "string" }, "route": { "nullable": true, "type": "string" }, "title": { "nullable": true, "type": "string" } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "object": { "enum": [ "user" ], "type": "string" }, "profile_picture_url": { "nullable": true, "type": "string" }, "username": { "nullable": true, "type": "string" } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "object": { "enum": [ "ledger_account" ], "type": "string" }, "owner": { "oneOf": [ { "properties": { "id": { "type": "string" }, "logo_url": { "nullable": true, "type": "string" }, "object": { "enum": [ "account" ], "type": "string" }, "route": { "nullable": true, "type": "string" }, "title": { "nullable": true, "type": "string" } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "object": { "enum": [ "user" ], "type": "string" }, "profile_picture_url": { "nullable": true, "type": "string" }, "username": { "nullable": true, "type": "string" } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "object", "id", "owner" ], "type": "object" }, { "properties": { "bank": { "nullable": true, "properties": { "account_name": { "nullable": true, "type": "string" }, "account_type": { "nullable": true, "type": "string" }, "bank_name": { "nullable": true, "type": "string" }, "last4": { "nullable": true, "type": "string" } }, "required": [ "bank_name", "account_name", "last4", "account_type" ], "type": "object" }, "card": { "nullable": true, "properties": { "brand": { "nullable": true, "type": "string" }, "exp_month": { "nullable": true, "type": "integer" }, "exp_year": { "nullable": true, "type": "integer" }, "last4": { "nullable": true, "type": "string" } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": "object" }, "email_identifier": { "nullable": true, "type": "string" }, "gateway_type": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "object": { "enum": [ "payment_method" ], "type": "string" }, "payment_method_type": { "nullable": true, "type": "string" } }, "required": [ "object", "id", "payment_method_type", "gateway_type", "card", "bank", "email_identifier" ], "type": "object" }, { "properties": { "account_reference": { "nullable": true, "type": "string" }, "destination_currency_code": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "institution_name": { "nullable": true, "type": "string" }, "nickname": { "nullable": true, "type": "string" }, "object": { "enum": [ "payout_method" ], "type": "string" }, "provider": { "nullable": true, "type": "string" } }, "required": [ "object", "id", "nickname", "institution_name", "account_reference", "provider", "destination_currency_code" ], "type": "object" }, { "type": "null" } ] }, "source": { "additionalProperties": true, "nullable": true, "properties": { "created_at": { "description": "Withdrawal creation time as an ISO 8601 timestamp (withdrawal sources only; requires payout:withdrawal:read).", "format": "date-time", "nullable": true, "type": "string" }, "estimated_arrival": { "description": "Estimated arrival as an ISO 8601 timestamp (withdrawal sources only; requires payout:withdrawal:read).", "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "object": { "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout (withdrawal sources only; requires payout:withdrawal:read).", "nullable": true, "type": "string" }, "payout_destination": { "description": "Payout destination display info (withdrawal sources only).", "nullable": true, "properties": { "icon_url": { "nullable": true, "type": "string" }, "payer_name": { "nullable": true, "type": "string" } }, "type": "object" }, "payout_token_nickname": { "description": "Saved payout destination nickname (withdrawal sources only).", "nullable": true, "type": "string" }, "status": { "description": "Withdrawal lifecycle status (withdrawal sources only; requires payout:withdrawal:read).", "nullable": true, "type": "string" } }, "required": [ "object", "id" ], "type": "object" } }, "required": [ "object", "id", "line_type", "amount", "currency", "posted_at", "created_at", "resource", "source" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "nullable": true, "type": "string" }, "has_next_page": { "type": "boolean" }, "has_previous_page": { "type": "boolean" }, "start_cursor": { "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "activities listed for a user" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither account_id nor user_id provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that owner is visible to the credential" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Financial Activity", "tags": [ "Ledgers" ] } }, "/forum_posts": { "get": { "description": "Returns a paginated list of forum posts within a specific experience, with optional filtering by parent post or pinned status.\n\nRequired permissions:\n - `forum:read`", "operationId": "listForumPost", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "experience_id", "required": true, "schema": { "description": "The unique identifier of the experience to list forum posts for.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "include_bounty_anchors", "required": false, "schema": { "description": "Whether to include top-level bounty discussion anchors as rich forum items.", "type": [ "boolean", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "parent_id", "required": false, "schema": { "description": "The unique identifier of a parent post to list comments for. When set, returns replies to that post.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "pinned", "required": false, "schema": { "description": "Whether to filter for only pinned posts. Set to true to return only pinned posts.", "type": [ "boolean", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ForumPost.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ForumPostListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "List forum posts", "tags": [ "Forum posts" ], "x-group-title": "Engagement" }, "post": { "description": "Create a new forum post or comment within an experience. Supports text content, attachments, polls, paywalling, and pinning. Pass experience_id 'public' with a company_id to post to a company's public forum.\n\nRequired permissions:\n - `forum:post:create`", "operationId": "createForumPost", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateForumPostV2", "properties": { "attachments": { "description": "A list of file attachments to include with the post, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "company_id": { "description": "The unique identifier of the company whose public forum to post in. Required when experience_id is 'public'. For example, 'biz_xxxxx'.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "content": { "description": "The main body of the post in Markdown format. For example, 'Check out this **update**'. Hidden if the post is paywalled and the viewer has not purchased access.", "type": [ "string", "null" ] }, "experience_id": { "description": "The unique identifier of the experience to create this post in. For example, 'exp_xxxxx'. Pass 'public' along with company_id to automatically use the company's public forum.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "is_mention": { "description": "Whether to send this post as a mention notification to all users in the experience who have mentions enabled.", "type": [ "boolean", "null" ] }, "parent_id": { "description": "The unique identifier of the parent post to comment on. Omit this field to create a top-level post.", "type": [ "string", "null" ] }, "paywall_amount": { "description": "The price to unlock this post in the specified paywall currency. For example, 5.00 for $5.00. When set, users must purchase access to view the post content.", "example": 6.9, "type": [ "number", "null" ] }, "paywall_currency": { "description": "The currency for the paywall price on this post. When set along with paywall_amount, users must purchase access to view the post content.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "pinned": { "description": "Whether this post should be pinned to the top of the forum.", "type": [ "boolean", "null" ] }, "poll": { "description": "A poll to attach to this post, allowing members to vote on options.", "properties": { "options": { "description": "The options for the poll. Must have sequential IDs starting from 1", "items": { "description": "Input type for a single poll option", "properties": { "id": { "description": "Sequential ID for the poll option (starting from '1')", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": "array" } }, "required": [ "options" ], "type": [ "object", "null" ] }, "rich_content": { "description": "The rich content of the post in Tiptap JSON format. When provided, takes priority over the markdown content field for rendering.", "type": [ "string", "null" ] }, "title": { "description": "The title of the post, displayed prominently at the top. Required for paywalled posts as it remains visible to non-purchasers.", "type": [ "string", "null" ] }, "visibility": { "description": "Controls who can see this forum post, such as members only or public.", "oneOf": [ { "$ref": "#/components/schemas/ForumPostVisibilityTypes" }, { "type": "null" } ] } }, "required": [ "experience_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumPost" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:post:create" ] } ], "summary": "Create forum post", "tags": [ "Forum posts" ], "x-group-title": "Engagement" } }, "/forum_posts/{id}": { "get": { "description": "Retrieves the details of an existing forum post.\n\nRequired permissions:\n - `forum:read`", "operationId": "retrieveForumPost", "parameters": [ { "description": "The unique identifier of the forum post to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumPost" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "Retrieve forum post", "tags": [ "Forum posts" ], "x-group-title": "Engagement" }, "patch": { "description": "Edit the content, attachments, pinned status, or visibility of an existing forum post or comment.", "operationId": "updateForumPost", "parameters": [ { "description": "The unique identifier of the forum post to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateForumPost", "properties": { "attachments": { "description": "A replacement list of file attachments for this post, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The updated body of the post in Markdown format. For example, 'Check out this **update**'. Hidden if the post is paywalled and the viewer has not purchased access.", "type": [ "string", "null" ] }, "is_pinned": { "description": "Whether this post should be pinned to the top of the forum. Only top-level posts can be pinned, not comments.", "type": [ "boolean", "null" ] }, "title": { "description": "The updated title of the post, displayed prominently at the top. Required for paywalled posts as it remains visible to non-purchasers.", "type": [ "string", "null" ] }, "visibility": { "description": "Controls who can see this forum post, such as members only or public.", "oneOf": [ { "$ref": "#/components/schemas/ForumPostVisibilityTypes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumPost" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update forum post", "tags": [ "Forum posts" ], "x-group-title": "Engagement" } }, "/forums": { "get": { "description": "Returns a paginated list of forums within a specific company, with optional filtering by product.\n\nRequired permissions:\n - `forum:read`", "operationId": "listForum", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list forums for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": false, "schema": { "description": "The unique identifier of a product to filter by. When set, only forums connected to this product are returned.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ForumFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ForumListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "List forums", "tags": [ "Forums" ], "x-group-title": "Engagement" } }, "/forums/{id}": { "get": { "description": "Retrieves the details of an existing forum.\n\nRequired permissions:\n - `forum:read`", "operationId": "retrieveForum", "parameters": [ { "description": "The unique identifier of the forum or experience to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forum" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "Retrieve forum", "tags": [ "Forums" ], "x-group-title": "Engagement" }, "patch": { "description": "Update moderation and notification settings for a forum, such as who can post, who can comment, and email notification preferences.\n\nRequired permissions:\n - `forum:moderate`", "operationId": "updateForum", "parameters": [ { "description": "The unique identifier of the forum to update. Accepts either an experience ID (e.g. 'exp_xxxxx') or a forum ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateForum", "properties": { "banned_words": { "description": "A list of words that are automatically blocked from posts in this forum. For example, ['spam', 'scam'].", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "banner_image": { "description": "The banner image displayed at the top of the forum page. Pass null to remove the existing banner.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "email_notification_preference": { "description": "Controls how email notifications are sent to members when new posts are created in this forum.", "oneOf": [ { "$ref": "#/components/schemas/ForumEmailNotificationPreferences" }, { "type": "null" } ] }, "who_can_comment": { "description": "Controls which roles are allowed to comment on posts in this forum.", "oneOf": [ { "$ref": "#/components/schemas/ForumWhoCanCommentTypes" }, { "type": "null" } ] }, "who_can_post": { "description": "Controls which roles are allowed to create new posts in this forum.", "oneOf": [ { "$ref": "#/components/schemas/ForumWhoCanPostTypes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forum" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:moderate" ] } ], "summary": "Update forum", "tags": [ "Forums" ], "x-group-title": "Engagement" } }, "/identity_profiles": { "get": { "description": "Returns a paginated list of identity profiles. When company_id is provided, lists IPs currently linked to that company's ledger. When omitted, lists IPs linked to any ledger the actor can read (including child companies under a parent).\n\nRequired permissions:\n - `identity:read`", "operationId": "listIdentityProfile", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to filter to. When omitted, returns IPs across all ledgers the actor can read.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "profile_type", "required": false, "schema": { "description": "Filter by profile type (individual or business).", "oneOf": [ { "$ref": "#/components/schemas/IdentityProfileKinds" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter by derived verification status.", "oneOf": [ { "$ref": "#/components/schemas/IdentityProfileStatuses" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for IdentityProfile.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/IdentityProfileListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "List identity profiles", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" } }, "/identity_profiles/{id}": { "delete": { "description": "Unlinks an IdentityProfile from a LedgerAccount (flips the matching link to is_current=false).", "operationId": "unlinkIdentityProfile", "parameters": [ { "description": "The ID of the IdentityProfile to unlink.", "in": "path", "name": "id", "required": true, "schema": { "example": "idpf_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "ledger_account_id", "required": true, "schema": { "description": "The ID of the LedgerAccount to unlink the identity profile from.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProfile" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Unlink an identity profile", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" }, "get": { "description": "Retrieves the details of an existing identity profile.\n\nRequired permissions:\n - `identity:read`", "operationId": "retrieveIdentityProfile", "parameters": [ { "description": "The unique identifier of the identity profile (idpf_xxx).", "in": "path", "name": "id", "required": true, "schema": { "example": "idpf_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProfile" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "Retrieve identity profile", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" } }, "/identity_profiles/{id}/verifications": { "get": { "description": "Returns a list of verifications attached to an identity profile, ordered by most recent first.\n\nRequired permissions:\n - `identity:read`", "operationId": "listVerificationsIdentityProfile", "parameters": [ { "description": "The unique identifier of the identity profile (idpf_xxx).", "in": "path", "name": "id", "required": true, "schema": { "example": "idpf_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Verification.", "properties": { "data": { "description": "A list of nodes.", "items": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "created_at": { "description": "When the verification record was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "session_url": { "description": "A URL the user can visit to complete the verification process. Null if the session does not require user interaction.", "example": "https://verify.stripe.com/session/abc123", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "session_url", "last_error_code", "last_error_reason", "created_at" ], "type": "object" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "List identity profile verifications", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" } }, "/invoices": { "get": { "description": "Returns a paginated list of invoices for a company, with optional filtering by product, status, collection method, and creation date.\n\nRequired permissions:\n - `invoice:basic:read`", "operationId": "listInvoice", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list invoices for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter invoices to only those associated with these specific product identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "collection_methods", "required": false, "schema": { "description": "Filter invoices by their collection method.", "items": { "$ref": "#/components/schemas/InvoiceCollectionMethods" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "statuses", "required": false, "schema": { "description": "Filter invoices by their current status.", "items": { "$ref": "#/components/schemas/InvoiceStatuses" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to order results by, such as creation date or due date.", "oneOf": [ { "$ref": "#/components/schemas/InvoicesSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return invoices created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return invoices created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicInvoice.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/InvoiceListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:basic:read" ] } ], "summary": "List invoices", "tags": [ "Invoices" ], "x-group-title": "Payins" }, "post": { "description": "Create an invoice for a customer. The invoice can be charged automatically using a stored payment method, or sent to the customer for manual payment.\n\nRequired permissions:\n - `invoice:create`", "operationId": "createInvoice", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateInvoice", "oneOf": [ { "description": "Autogenerated input type of CreateInvoice", "properties": { "automatically_finalizes_at": { "description": "The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email to the customer at the specified time.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "billing_address": { "description": "Inline billing address to create a new mailing address for this invoice. Cannot be used together with mailing_address_id.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "phone": { "description": "The phone number of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] }, "tax_id_type": { "description": "The type of tax identifier.", "oneOf": [ { "$ref": "#/components/schemas/TaxIdentifierTypes" }, { "type": "null" } ] }, "tax_id_value": { "description": "The value of the tax identifier.", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "charge_buyer_fee": { "description": "Whether to charge the customer a buyer fee on this invoice.", "type": [ "boolean", "null" ] }, "collection_method": { "$ref": "#/components/schemas/InvoiceCollectionMethods", "description": "How the invoice should be collected. Use charge_automatically to charge a stored payment method, or send_invoice to email the customer." }, "company_id": { "description": "The unique identifier of the company to create this invoice for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "customer_name": { "description": "The name of the customer. Required when creating an invoice for a customer who is not yet a member of the company.", "type": [ "string", "null" ] }, "due_date": { "description": "The date by which the invoice must be paid. Required unless save_as_draft is true.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer. Required when creating an invoice for a customer who is not yet a member of the company.", "type": [ "string", "null" ] }, "line_items": { "description": "Optional line items that break down the invoice total. When provided, the sum of (quantity * unit_price) for all items must equal the plan price.", "items": { "description": "A single line item to include on the invoice, with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "type": "string" }, "quantity": { "description": "The quantity of this line item. Defaults to 1.", "example": 6.9, "type": [ "number", "null" ] }, "unit_price": { "description": "The unit price for this line item. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": "number" } }, "required": [ "label", "unit_price" ], "type": "object" }, "type": [ "array", "null" ] }, "mailing_address_id": { "description": "The unique identifier of an existing mailing address to attach to this invoice. Cannot be used together with billing_address.", "example": "ma_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "member_id": { "description": "The unique identifier of an existing member to create this invoice for. If not provided, you must supply an email_address and customer_name.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_method_id": { "description": "The unique identifier of the payment method to charge. Required when collection_method is charge_automatically.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_token_id": { "description": "The payment token ID to use for this invoice. If using charge_automatically, you must provide a payment_token.", "example": "payt_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "plan": { "description": "The plan attributes defining the price, currency, and billing interval for this invoice.", "properties": { "billing_period": { "description": "The interval in days at which the plan charges (renewal plans).", "example": 42, "type": [ "integer", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "custom_fields": { "description": "An array of custom field objects.", "items": { "properties": { "field_type": { "$ref": "#/components/schemas/CustomFieldTypes", "description": "The type of the custom field." }, "id": { "description": "The ID of the custom field (if being updated)", "type": [ "string", "null" ] }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "example": 42, "type": [ "integer", "null" ] }, "placeholder": { "description": "The placeholder value of the field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": [ "boolean", "null" ] } }, "required": [ "field_type", "name" ], "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "The description of the plan.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires and revokes access (expiration plans). For example, 365 for a one-year access period.", "example": 42, "type": [ "integer", "null" ] }, "initial_price": { "description": "An additional amount charged upon first purchase. Use only if a one time payment OR you want to charge an additional amount on top of the renewal price. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": [ "number", "null" ] }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "legacy_payment_method_controls": { "description": "Whether this plan uses legacy payment method controls", "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "The explicit payment method configuration for the plan. If not provided, the platform or company's defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "plan_type": { "description": "Indicates if the plan is a one time payment or recurring.", "oneOf": [ { "$ref": "#/components/schemas/PlanTypes" }, { "type": "null" } ] }, "release_method": { "description": "This is the release method the business uses to sell this plan.", "oneOf": [ { "$ref": "#/components/schemas/ReleaseMethod" }, { "type": "null" } ] }, "renewal_price": { "description": "The amount the customer is charged every billing period. Use only if a recurring payment. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": [ "number", "null" ] }, "stock": { "description": "The number of units available for purchase.", "example": 42, "type": [ "integer", "null" ] }, "trial_period_days": { "description": "The number of free trial days added before a renewal plan.", "example": 42, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "When true, the plan has unlimited stock (stock field is ignored). When false, purchases are limited by the stock field.", "type": [ "boolean", "null" ] }, "visibility": { "description": "Shows or hides the plan from public/business view.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "product": { "description": "The properties of the product to create for this invoice. Provide this to create a new product inline.", "properties": { "product_tax_code_id": { "description": "The ID of the product tax code to apply to this product.", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "The title of the product.", "type": "string" } }, "required": [ "title" ], "type": "object" }, "save_as_draft": { "description": "When true, creates the invoice as a draft without sending or charging. Relaxes customer and due date requirements.", "type": [ "boolean", "null" ] }, "subscription_billing_anchor_at": { "description": "The date that defines when the subscription billing cycle should start. When set on a renewal plan invoice, this anchors all future billing periods to this date.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "company_id", "plan", "collection_method", "product" ], "title": "CreateInvoiceInputWithProduct", "type": "object" }, { "description": "Autogenerated input type of CreateInvoice", "properties": { "automatically_finalizes_at": { "description": "The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email to the customer at the specified time.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "billing_address": { "description": "Inline billing address to create a new mailing address for this invoice. Cannot be used together with mailing_address_id.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "phone": { "description": "The phone number of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] }, "tax_id_type": { "description": "The type of tax identifier.", "oneOf": [ { "$ref": "#/components/schemas/TaxIdentifierTypes" }, { "type": "null" } ] }, "tax_id_value": { "description": "The value of the tax identifier.", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "charge_buyer_fee": { "description": "Whether to charge the customer a buyer fee on this invoice.", "type": [ "boolean", "null" ] }, "collection_method": { "$ref": "#/components/schemas/InvoiceCollectionMethods", "description": "How the invoice should be collected. Use charge_automatically to charge a stored payment method, or send_invoice to email the customer." }, "company_id": { "description": "The unique identifier of the company to create this invoice for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "customer_name": { "description": "The name of the customer. Required when creating an invoice for a customer who is not yet a member of the company.", "type": [ "string", "null" ] }, "due_date": { "description": "The date by which the invoice must be paid. Required unless save_as_draft is true.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer. Required when creating an invoice for a customer who is not yet a member of the company.", "type": [ "string", "null" ] }, "line_items": { "description": "Optional line items that break down the invoice total. When provided, the sum of (quantity * unit_price) for all items must equal the plan price.", "items": { "description": "A single line item to include on the invoice, with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "type": "string" }, "quantity": { "description": "The quantity of this line item. Defaults to 1.", "example": 6.9, "type": [ "number", "null" ] }, "unit_price": { "description": "The unit price for this line item. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": "number" } }, "required": [ "label", "unit_price" ], "type": "object" }, "type": [ "array", "null" ] }, "mailing_address_id": { "description": "The unique identifier of an existing mailing address to attach to this invoice. Cannot be used together with billing_address.", "example": "ma_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "member_id": { "description": "The unique identifier of an existing member to create this invoice for. If not provided, you must supply an email_address and customer_name.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_method_id": { "description": "The unique identifier of the payment method to charge. Required when collection_method is charge_automatically.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_token_id": { "description": "The payment token ID to use for this invoice. If using charge_automatically, you must provide a payment_token.", "example": "payt_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "plan": { "description": "The plan attributes defining the price, currency, and billing interval for this invoice.", "properties": { "billing_period": { "description": "The interval in days at which the plan charges (renewal plans).", "example": 42, "type": [ "integer", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "custom_fields": { "description": "An array of custom field objects.", "items": { "properties": { "field_type": { "$ref": "#/components/schemas/CustomFieldTypes", "description": "The type of the custom field." }, "id": { "description": "The ID of the custom field (if being updated)", "type": [ "string", "null" ] }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "example": 42, "type": [ "integer", "null" ] }, "placeholder": { "description": "The placeholder value of the field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": [ "boolean", "null" ] } }, "required": [ "field_type", "name" ], "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "The description of the plan.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires and revokes access (expiration plans). For example, 365 for a one-year access period.", "example": 42, "type": [ "integer", "null" ] }, "initial_price": { "description": "An additional amount charged upon first purchase. Use only if a one time payment OR you want to charge an additional amount on top of the renewal price. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": [ "number", "null" ] }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "legacy_payment_method_controls": { "description": "Whether this plan uses legacy payment method controls", "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "The explicit payment method configuration for the plan. If not provided, the platform or company's defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "plan_type": { "description": "Indicates if the plan is a one time payment or recurring.", "oneOf": [ { "$ref": "#/components/schemas/PlanTypes" }, { "type": "null" } ] }, "release_method": { "description": "This is the release method the business uses to sell this plan.", "oneOf": [ { "$ref": "#/components/schemas/ReleaseMethod" }, { "type": "null" } ] }, "renewal_price": { "description": "The amount the customer is charged every billing period. Use only if a recurring payment. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": [ "number", "null" ] }, "stock": { "description": "The number of units available for purchase.", "example": 42, "type": [ "integer", "null" ] }, "trial_period_days": { "description": "The number of free trial days added before a renewal plan.", "example": 42, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "When true, the plan has unlimited stock (stock field is ignored). When false, purchases are limited by the stock field.", "type": [ "boolean", "null" ] }, "visibility": { "description": "Shows or hides the plan from public/business view.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "product_id": { "description": "The unique identifier of an existing product to create this invoice for.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "save_as_draft": { "description": "When true, creates the invoice as a draft without sending or charging. Relaxes customer and due date requirements.", "type": [ "boolean", "null" ] }, "subscription_billing_anchor_at": { "description": "The date that defines when the subscription billing cycle should start. When set on a renewal plan invoice, this anchors all future billing periods to this date.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "company_id", "plan", "collection_method", "product_id" ], "title": "CreateInvoiceInputWithProductId", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:create" ] } ], "summary": "Create invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "/invoices/{id}": { "delete": { "description": "Delete a draft invoice.\n\nRequired permissions:\n - `invoice:update`", "operationId": "deleteInvoice", "parameters": [ { "description": "The unique identifier of the draft invoice to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "inv_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:update" ] } ], "summary": "Delete invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" }, "get": { "description": "Retrieves the details of an existing invoice.\n\nRequired permissions:\n - `invoice:basic:read`", "operationId": "retrieveInvoice", "parameters": [ { "description": "The unique identifier of the invoice, or a secure token.", "in": "path", "name": "id", "required": true, "schema": { "example": "inv_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:basic:read" ] } ], "summary": "Retrieve invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" }, "patch": { "description": "Update a draft invoice's details.\n\nRequired permissions:\n - `invoice:update`", "operationId": "updateInvoice", "parameters": [ { "description": "The unique identifier of the invoice to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "inv_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateInvoice", "properties": { "automatically_finalizes_at": { "description": "The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email at the specified time.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "billing_address": { "description": "Inline billing address to create or update a mailing address for this invoice.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "phone": { "description": "The phone number of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] }, "tax_id_type": { "description": "The type of tax identifier.", "oneOf": [ { "$ref": "#/components/schemas/TaxIdentifierTypes" }, { "type": "null" } ] }, "tax_id_value": { "description": "The value of the tax identifier.", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "charge_buyer_fee": { "description": "Whether to charge the customer a buyer fee on this invoice.", "type": [ "boolean", "null" ] }, "collection_method": { "description": "How the invoice should be collected.", "oneOf": [ { "$ref": "#/components/schemas/InvoiceCollectionMethods" }, { "type": "null" } ] }, "customer_name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "due_date": { "description": "The date by which the invoice must be paid.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer.", "type": [ "string", "null" ] }, "line_items": { "description": "Line items that break down the invoice total.", "items": { "description": "A single line item to include on the invoice, with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "type": "string" }, "quantity": { "description": "The quantity of this line item. Defaults to 1.", "example": 6.9, "type": [ "number", "null" ] }, "unit_price": { "description": "The unit price for this line item. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": "number" } }, "required": [ "label", "unit_price" ], "type": "object" }, "type": [ "array", "null" ] }, "mailing_address_id": { "description": "The unique identifier of an existing mailing address to attach.", "example": "ma_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "member_id": { "description": "The unique identifier of a member to assign as the customer.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_method_id": { "description": "The unique identifier of the payment method to charge.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "plan": { "description": "Updated plan attributes.", "properties": { "billing_period": { "description": "The interval in days at which the plan charges (renewal plans).", "example": 42, "type": [ "integer", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "custom_fields": { "description": "An array of custom field objects.", "items": { "properties": { "field_type": { "$ref": "#/components/schemas/CustomFieldTypes", "description": "The type of the custom field." }, "id": { "description": "The ID of the custom field (if being updated)", "type": [ "string", "null" ] }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "example": 42, "type": [ "integer", "null" ] }, "placeholder": { "description": "The placeholder value of the field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": [ "boolean", "null" ] } }, "required": [ "field_type", "name" ], "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "The description of the plan.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires and revokes access (expiration plans). For example, 365 for a one-year access period.", "example": 42, "type": [ "integer", "null" ] }, "initial_price": { "description": "An additional amount charged upon first purchase. Use only if a one time payment OR you want to charge an additional amount on top of the renewal price. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": [ "number", "null" ] }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "legacy_payment_method_controls": { "description": "Whether this plan uses legacy payment method controls", "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "The explicit payment method configuration for the plan. If not provided, the platform or company's defaults will apply.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": [ "boolean", "null" ] } }, "required": [ "disabled", "enabled" ], "type": [ "object", "null" ] }, "plan_type": { "description": "Indicates if the plan is a one time payment or recurring.", "oneOf": [ { "$ref": "#/components/schemas/PlanTypes" }, { "type": "null" } ] }, "release_method": { "description": "This is the release method the business uses to sell this plan.", "oneOf": [ { "$ref": "#/components/schemas/ReleaseMethod" }, { "type": "null" } ] }, "renewal_price": { "description": "The amount the customer is charged every billing period. Use only if a recurring payment. Provided as a number in the specified currency. Eg: 10.43 for $10.43", "example": 6.9, "type": [ "number", "null" ] }, "stock": { "description": "The number of units available for purchase.", "example": 42, "type": [ "integer", "null" ] }, "trial_period_days": { "description": "The number of free trial days added before a renewal plan.", "example": 42, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "When true, the plan has unlimited stock (stock field is ignored). When false, purchases are limited by the stock field.", "type": [ "boolean", "null" ] }, "visibility": { "description": "Shows or hides the plan from public/business view.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] }, "product_id": { "description": "The unique identifier of an existing product to attach to this invoice. Only allowed while the invoice is still a draft.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "subscription_billing_anchor_at": { "description": "The date that defines when the subscription billing cycle should start.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:update" ] } ], "summary": "Update invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "/invoices/{id}/mark_paid": { "post": { "description": "Mark an open invoice as paid when payment was collected outside of Whop.\n\nRequired permissions:\n - `invoice:update`", "operationId": "markPaidInvoice", "parameters": [ { "description": "The unique identifier of the invoice to mark as paid.", "in": "path", "name": "id", "required": true, "schema": { "example": "inv_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:update" ] } ], "summary": "Mark paid invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "/invoices/{id}/mark_uncollectible": { "post": { "description": "Mark an open invoice as uncollectible when payment is not expected.\n\nRequired permissions:\n - `invoice:update`", "operationId": "markUncollectibleInvoice", "parameters": [ { "description": "The unique identifier of the invoice to mark as uncollectible.", "in": "path", "name": "id", "required": true, "schema": { "example": "inv_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:update" ] } ], "summary": "Mark uncollectible invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "/invoices/{id}/void": { "post": { "description": "Void an open invoice so it can no longer be paid. Voiding is permanent and cannot be undone.\n\nRequired permissions:\n - `invoice:update`", "operationId": "voidInvoice", "parameters": [ { "description": "The unique identifier of the invoice to void.", "in": "path", "name": "id", "required": true, "schema": { "example": "inv_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "invoice:update" ] } ], "summary": "Void invoice", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "/leads": { "get": { "description": "Returns a paginated list of leads for a company, with optional filtering by product and creation date.\n\nRequired permissions:\n - `lead:basic:read`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "listLead", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list leads for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return leads created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return leads created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter leads to only those associated with these specific product identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Lead.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/LeadListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:basic:read", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "List leads", "tags": [ "Leads" ], "x-group-title": "CRM" }, "post": { "description": "Record a new lead for a company, capturing a potential customer's interest in a specific product.\n\nRequired permissions:\n - `lead:manage`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "createLead", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateLeadV2", "properties": { "company_id": { "description": "The unique identifier of the company to create the lead for, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "A JSON object of custom metadata to attach to the lead for tracking purposes.", "type": [ "object", "null" ] }, "product_id": { "description": "The unique identifier of the product the lead is interested in, starting with 'prod_'.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "referrer": { "description": "The referral URL that brought the lead to the company, such as 'https://example.com/landing'.", "type": [ "string", "null" ] }, "user_id": { "description": "The unique identifier of the user to record as the lead. If authenticated as a user, that user is used automatically.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "company_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:manage", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "Create lead", "tags": [ "Leads" ], "x-group-title": "CRM" } }, "/leads/{id}": { "get": { "description": "Retrieves the details of an existing lead.\n\nRequired permissions:\n - `lead:basic:read`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "retrieveLead", "parameters": [ { "description": "The unique identifier of the lead to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "lead_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:basic:read", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "Retrieve lead", "tags": [ "Leads" ], "x-group-title": "CRM" }, "patch": { "description": "Update the metadata or referrer information on an existing lead record.\n\nRequired permissions:\n - `lead:manage`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "updateLead", "parameters": [ { "description": "The unique identifier of the lead to update, starting with 'lead_'.", "in": "path", "name": "id", "required": true, "schema": { "example": "lead_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateLead", "properties": { "metadata": { "additionalProperties": true, "description": "A JSON object of custom metadata to set on the lead, replacing any existing metadata.", "type": [ "object", "null" ] }, "referrer": { "description": "The updated referral URL for the lead, such as 'https://example.com/landing'.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:manage", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "Update lead", "tags": [ "Leads" ], "x-group-title": "CRM" } }, "/ledger_accounts/{id}": { "get": { "description": "Retrieves the details of an existing ledger account.\n\nRequired permissions:\n - `company:balance:read`\n - `payout:account:read`", "operationId": "retrieveLedgerAccount", "parameters": [ { "description": "The identifier to look up the ledger account. Accepts a user ID ('user_xxx'), company ID ('biz_xxx'), or ledger account ID ('ldgr_xxx').", "in": "path", "name": "id", "required": true, "schema": { "example": "ldgr_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccount" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:balance:read", "payout:account:read" ] } ], "summary": "Retrieve ledger account", "tags": [ "Ledger accounts" ], "x-group-title": "Payouts" } }, "/members": { "get": { "description": "Returns a paginated list of members for a company, with extensive filtering by product, plan, status, access level, and more.\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `member:phone:read`", "operationId": "listMember", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list members for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The column to sort members by, such as creation date or revenue.", "oneOf": [ { "$ref": "#/components/schemas/MembersSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return members created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return members created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "access_level", "required": false, "schema": { "description": "Filter members by their current access level to the product.", "oneOf": [ { "$ref": "#/components/schemas/AccessLevel" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter members to only those belonging to these specific products.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "plan_ids", "required": false, "schema": { "description": "Filter members to only those subscribed to these specific plans.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_ids", "required": false, "schema": { "description": "Filter members to only those matching these specific user identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "statuses", "required": false, "schema": { "description": "Filter members by their current subscription status.", "items": { "$ref": "#/components/schemas/MemberStatuses" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "promo_code_ids", "required": false, "schema": { "description": "Filter members to only those who used these specific promo codes.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "most_recent_actions", "required": false, "schema": { "description": "Filter members by their most recent activity type.", "items": { "$ref": "#/components/schemas/MemberMostRecentActions" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Search members by name, username, or email. Email filtering requires the member:email:read permission.", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CompanyMember.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/MemberListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:basic:read", "member:email:read", "member:phone:read" ] } ], "summary": "List members", "tags": [ "Members" ], "x-group-title": "CRM" } }, "/members/{id}": { "get": { "description": "Retrieves the details of an existing member.\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `member:phone:read`", "operationId": "retrieveMember", "parameters": [ { "description": "The unique identifier of the member to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:basic:read", "member:email:read", "member:phone:read" ] } ], "summary": "Retrieve member", "tags": [ "Members" ], "x-group-title": "CRM" } }, "/memberships": { "get": { "description": "Returns a paginated list of memberships, with optional filtering by product, plan, status, and user.\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`", "operationId": "listMembership", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list memberships for. Required when using an API key.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to sort results by. Null uses the default sort order.", "oneOf": [ { "$ref": "#/components/schemas/MembershipsSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter to only memberships belonging to these product identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "statuses", "required": false, "schema": { "description": "Filter to only memberships matching these statuses.", "items": { "$ref": "#/components/schemas/MembershipStatus" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "cancel_options", "required": false, "schema": { "description": "Filter to only memberships matching these cancellation reasons.", "items": { "$ref": "#/components/schemas/CancelOptions" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "plan_ids", "required": false, "schema": { "description": "Filter to only memberships belonging to these plan identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_ids", "required": false, "schema": { "description": "Filter to only memberships belonging to these user identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "promo_code_ids", "required": false, "schema": { "description": "Filter to only memberships that used these promo code identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return memberships created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return memberships created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicMembership.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/MembershipListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:basic:read", "member:email:read" ] } ], "summary": "List memberships", "tags": [ "Memberships" ], "x-group-title": "CRM" }, "post": { "description": "Grant a free membership on a free plan to a user. Use this to give users access to a product without charging them. The plan's initial and renewal prices must both be zero.\n\nRequired permissions:\n - `membership:create`\n - `member:email:read`\n - `member:basic:read`", "operationId": "createMembership", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateMembership", "properties": { "metadata": { "additionalProperties": true, "description": "Custom key-value pairs to attach to the membership.", "type": [ "object", "null" ] }, "plan_id": { "description": "The unique identifier of the free plan to grant. The plan's initial and renewal prices must both be zero.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "The unique identifier of the user to grant the membership to.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_id", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "membership:create", "member:email:read", "member:basic:read" ] } ], "summary": "Create membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}": { "get": { "description": "Retrieves the details of an existing membership.\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`", "operationId": "retrieveMembership", "parameters": [ { "description": "The unique identifier of the membership, or a license key.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:basic:read", "member:email:read" ] } ], "summary": "Retrieve membership", "tags": [ "Memberships" ], "x-group-title": "CRM" }, "patch": { "description": "Update a membership's metadata or other mutable properties.\n\nRequired permissions:\n - `member:manage`\n - `member:email:read`\n - `member:basic:read`", "operationId": "updateMembership", "parameters": [ { "description": "The unique identifier of the membership to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateMembershipV2", "properties": { "metadata": { "additionalProperties": true, "description": "A JSON object of key-value pairs to store on the membership. Replaces any existing metadata.", "type": [ "object", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:manage", "member:email:read", "member:basic:read" ] } ], "summary": "Update membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}/add_free_days": { "post": { "description": "Add free days to extend a membership's current billing period, expiration date, or Stripe trial.\n\nRequired permissions:\n - `member:manage`\n - `member:email:read`\n - `member:basic:read`", "operationId": "addFreeDaysMembership", "parameters": [ { "description": "The unique identifier of the membership.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for AddFreeDaysToMembership", "properties": { "free_days": { "description": "The number of free days to add (1-1095). Extends the billing period, expiration date, or Stripe trial depending on plan type.", "example": 42, "type": "integer" } }, "required": [ "free_days" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:manage", "member:email:read", "member:basic:read" ] } ], "summary": "Add free days membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}/cancel": { "post": { "description": "Cancel a membership either immediately or at the end of the current billing period. Immediate cancellation revokes access right away.\n\nRequired permissions:\n - `membership:cancel`\n - `member:email:read`\n - `member:basic:read`", "operationId": "cancelMembership", "parameters": [ { "description": "The unique identifier of the membership to cancel.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CancelMembership", "properties": { "cancellation_mode": { "description": "Whether to cancel immediately or at the end of the current billing period. Defaults to at_period_end.", "oneOf": [ { "$ref": "#/components/schemas/MembershipCancellationModes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "membership:cancel", "member:email:read", "member:basic:read" ] } ], "summary": "Cancel membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}/pause": { "post": { "description": "Pause a membership's recurring payments. The customer retains access but will not be charged until the membership is resumed.\n\nRequired permissions:\n - `member:manage`\n - `member:email:read`\n - `member:basic:read`", "operationId": "pauseMembership", "parameters": [ { "description": "The unique identifier of the membership to pause.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for PauseMembership", "properties": { "void_payments": { "description": "Whether to void any outstanding past-due payments on this membership, preventing future collection attempts.", "type": [ "boolean", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:manage", "member:email:read", "member:basic:read" ] } ], "summary": "Pause membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}/resume": { "post": { "description": "Resume a previously paused membership's recurring payments. Billing resumes on the next cycle.\n\nRequired permissions:\n - `member:manage`\n - `member:email:read`\n - `member:basic:read`", "operationId": "resumeMembership", "parameters": [ { "description": "The unique identifier of the membership to resume.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:manage", "member:email:read", "member:basic:read" ] } ], "summary": "Resume membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}/uncancel": { "post": { "description": "Reverse a pending cancellation for a membership that was scheduled to cancel at period end.\n\nRequired permissions:\n - `member:manage`\n - `member:email:read`\n - `member:basic:read`", "operationId": "uncancelMembership", "parameters": [ { "description": "The unique identifier of the membership to uncancel.", "in": "path", "name": "id", "required": true, "schema": { "example": "mem_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:manage", "member:email:read", "member:basic:read" ] } ], "summary": "Uncancel membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/messages": { "get": { "description": "Returns a paginated list of messages within a specific experience chat, DM, or group chat channel, sorted by creation time.\n\nRequired permissions:\n - `chat:read`", "operationId": "listMessage", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "channel_id", "required": true, "schema": { "description": "The unique identifier of the channel or experience to list messages for.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for messages by creation time. Use 'asc' for oldest first or 'desc' for newest first.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsPost.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/MessageListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "List messages", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "post": { "description": "Send a new message in an experience chat, DM, or group chat channel. Supports text content, attachments, polls, and replies.\n\nRequired permissions:\n - `chat:message:create`", "operationId": "createMessage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateMessage", "properties": { "attachments": { "description": "A list of file attachments to include with the message, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "auto_detect_links": { "description": "Automatically detect URLs in the message and generate link previews.", "type": [ "boolean", "null" ] }, "channel_id": { "description": "The unique identifier of the channel or experience to send the message in. For example, 'exp_xxxxx' or 'feed_xxxxx'.", "type": "string" }, "content": { "description": "The body of the message in Markdown format. For example, 'Hello **world**'.", "type": "string" }, "poll": { "description": "A poll to attach to this message, allowing recipients to vote on options.", "properties": { "options": { "description": "The options for the poll. Must have sequential IDs starting from 1", "items": { "description": "Input type for a single poll option", "properties": { "id": { "description": "Sequential ID for the poll option (starting from '1')", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": "array" } }, "required": [ "options" ], "type": [ "object", "null" ] }, "replying_to_message_id": { "description": "The unique identifier of the message this is replying to, creating a threaded reply.", "type": [ "string", "null" ] } }, "required": [ "channel_id", "content" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:message:create" ] } ], "summary": "Create message", "tags": [ "Messages" ], "x-group-title": "Engagement" } }, "/messages/{id}": { "delete": { "description": "Permanently delete a message from an experience chat, DM, or group chat channel. Only the message author or a channel admin can delete a message.\n\nRequired permissions:\n - `chat:message:create`", "operationId": "deleteMessage", "parameters": [ { "description": "The unique identifier of the message to delete.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:message:create" ] } ], "summary": "Delete message", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing message.\n\nRequired permissions:\n - `chat:read`", "operationId": "retrieveMessage", "parameters": [ { "description": "The unique identifier of the message to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "Retrieve message", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "patch": { "description": "Edit the content, attachments, or pinned status of an existing message in an experience chat, DM, or group chat channel.", "operationId": "updateMessage", "parameters": [ { "description": "The unique identifier of the message to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateMessage", "properties": { "attachments": { "description": "A replacement list of file attachments for this message, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The updated body of the message in Markdown format. For example, 'Hello **world**'.", "type": [ "string", "null" ] }, "is_pinned": { "description": "Whether this message should be pinned to the top of the channel.", "type": [ "boolean", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update message", "tags": [ "Messages" ], "x-group-title": "Engagement" } }, "/notifications": { "post": { "description": "Send a push notification to users in an experience or company team. The notification is processed asynchronously and supports targeting specific users.\n\nRequired permissions:\n - `notification:create`", "operationId": "createNotification", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for SendNotificationV2", "oneOf": [ { "description": "Autogenerated input type of SendNotificationV2", "properties": { "company_id": { "description": "The unique identifier of the company to target. Only team members of this company will receive the notification. Clicking the notification opens your dashboard app view.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "content": { "description": "The main body text of the notification displayed to the user.", "type": "string" }, "icon_user_id": { "description": "The unique identifier of a user whose profile picture will be used as the notification icon. Defaults to the experience or company avatar when not provided.", "type": [ "string", "null" ] }, "rest_path": { "description": "A path segment appended to the generated deep link that opens your app. Use [restPath] in your app path configuration to read this parameter. For example, '/settings/billing'.", "type": [ "string", "null" ] }, "subtitle": { "description": "An optional secondary line of text displayed below the title in the notification.", "type": [ "string", "null" ] }, "title": { "description": "The headline text of the notification, displayed prominently to the user.", "type": "string" }, "user_ids": { "description": "An optional list of user IDs to narrow the audience. When provided, only these users receive the notification, provided they are in the targeted experience or company.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "content", "title", "company_id" ], "title": "SendNotificationV2InputWithCompanyId", "type": "object" }, { "description": "Autogenerated input type of SendNotificationV2", "properties": { "content": { "description": "The main body text of the notification displayed to the user.", "type": "string" }, "experience_id": { "description": "The unique identifier of the experience to target. All users with access to this experience will receive the notification. Clicking the notification opens the experience view.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "icon_user_id": { "description": "The unique identifier of a user whose profile picture will be used as the notification icon. Defaults to the experience or company avatar when not provided.", "type": [ "string", "null" ] }, "rest_path": { "description": "A path segment appended to the generated deep link that opens your app. Use [restPath] in your app path configuration to read this parameter. For example, '/settings/billing'.", "type": [ "string", "null" ] }, "subtitle": { "description": "An optional secondary line of text displayed below the title in the notification.", "type": [ "string", "null" ] }, "title": { "description": "The headline text of the notification, displayed prominently to the user.", "type": "string" }, "user_ids": { "description": "An optional list of user IDs to narrow the audience. When provided, only these users receive the notification, provided they are in the targeted experience or company.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "content", "title", "experience_id" ], "title": "SendNotificationV2InputWithExperienceId", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Response from queuing a notification", "properties": { "success": { "description": "Whether the notification was successfully queued for delivery", "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "notification:create" ] } ], "summary": "Create notification", "tags": [ "Notifications" ], "x-group-title": "Engagement" } }, "/payment_methods": { "get": { "description": "Returns a paginated list of payment methods for a member or company, with optional filtering by creation date. A payment method is a stored representation of how a customer intends to pay, such as a card, bank account, or digital wallet.\n\nRequired permissions:\n - `member:payment_methods:read`", "operationId": "listPaymentMethod", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member to list payment methods for.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company. Provide either this or member_id, not both.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return payment methods created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return payment methods created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PaymentMethodInterface.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/PaymentMethodListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:payment_methods:read" ] } ], "summary": "List payment methods", "tags": [ "Payment methods" ], "x-group-title": "Payins" } }, "/payment_methods/{id}": { "delete": { "description": "Delete a saved payment method. Cannot delete a payment method attached to an active subscription.\n\nRequired permissions:\n - `member:payment_methods:manage`", "operationId": "deletePaymentMethod", "parameters": [ { "description": "The unique identifier of the payment method to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "payt_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company. Provide either this or member_id, not both.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member. Provide either this or company_id, not both.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:payment_methods:manage" ] } ], "summary": "Delete payment method", "tags": [ "Payment methods" ], "x-group-title": "Payins" }, "get": { "description": "Retrieves the details of an existing payment method.\n\nRequired permissions:\n - `member:payment_methods:read`", "operationId": "retrievePaymentMethod", "parameters": [ { "description": "The unique identifier of the payment method.", "in": "path", "name": "id", "required": true, "schema": { "example": "payt_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company. Provide either this or member_id, not both.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member. Provide either this or company_id, not both.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:payment_methods:read" ] } ], "summary": "Retrieve payment method", "tags": [ "Payment methods" ], "x-group-title": "Payins" } }, "/payments": { "get": { "description": "Returns a paginated list of payments for the actor in context, with optional filtering by product, plan, status, billing reason, currency, and creation date.\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`", "operationId": "listPayment", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list payments for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to order results by, such as creation date.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptV2Order" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter payments to only those associated with these specific product identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "billing_reasons", "required": false, "schema": { "description": "Filter payments by their billing reason.", "items": { "$ref": "#/components/schemas/BillingReasons" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "currencies", "required": false, "schema": { "description": "Filter payments by their currency code.", "items": { "$ref": "#/components/schemas/Currencies" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "plan_ids", "required": false, "schema": { "description": "Filter payments to only those associated with these specific plan identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "statuses", "required": false, "schema": { "description": "Filter payments by their current status.", "items": { "$ref": "#/components/schemas/ReceiptStatus" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "substatuses", "required": false, "schema": { "description": "Filter payments by their current substatus for more granular filtering.", "items": { "$ref": "#/components/schemas/FriendlyReceiptStatus" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "include_free", "required": false, "schema": { "description": "Whether to include payments with a zero amount.", "type": [ "boolean", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return payments created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return payments created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "updated_before", "required": false, "schema": { "description": "Only return payments last updated before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "updated_after", "required": false, "schema": { "description": "Only return payments last updated after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Search payments by user ID, membership ID, user email, name, or username. Email filtering requires the member:email:read permission.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "checkout_configuration_ids", "required": false, "schema": { "description": "Only return payments from these checkout configurations.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Receipt.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/PaymentListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:basic:read", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "promo_code:basic:read" ] } ], "summary": "List payments", "tags": [ "Payments" ], "x-group-title": "Payins" }, "post": { "description": "Charge an existing member off-session using one of their stored payment methods. You can provide an existing plan, or create a new one in-line. This endpoint will respond with a payment object immediately, but the payment is processed asynchronously in the background. Use webhooks to be notified when the payment succeeds or fails.\n\nRequired permissions:\n - `payment:charge`\n - `plan:create`\n - `access_pass:create`\n - `access_pass:update`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`", "operationId": "createPayment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreatePayment", "oneOf": [ { "description": "Autogenerated input type of CreatePayment", "properties": { "company_id": { "description": "The ID of the company to create the payment for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "member_id": { "description": "The ID of the member to create the payment for.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata to attach to the payment.", "type": [ "object", "null" ] }, "payment_method_id": { "description": "The ID of the payment method to use for the payment. It must be connected to the Member being charged.", "example": "pmt_xxxxxxxxxxxxxx", "type": "string" }, "plan": { "description": "Pass this object to create a new plan for this payment", "properties": { "application_fee_amount": { "description": "The application fee amount collected by the platform from this connected account. Provided as a number in dollars (e.g., 5.00 for $5.00). Must be less than the total payment amount. Only valid for connected accounts with a parent company.", "example": 6.9, "type": [ "number", "null" ] }, "billing_period": { "description": "The interval in days at which the plan charges (renewal plans). For example, 30 for monthly billing.", "example": 42, "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The respective currency identifier for the plan." }, "description": { "description": "The description of the plan.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires and revokes access (expiration plans). For example, 365 for one year.", "example": 42, "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Whether to force the creation of a new plan even if one with the same attributes already exists.", "type": [ "boolean", "null" ] }, "initial_price": { "description": "An additional amount charged upon first purchase. Provided as a number in the specified currency. Eg: 10.43 for $10.43 USD.", "example": 6.9, "type": [ "number", "null" ] }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "plan_type": { "description": "Indicates if the plan is a one time payment or recurring.", "oneOf": [ { "$ref": "#/components/schemas/PlanTypes" }, { "type": "null" } ] }, "product": { "description": "Pass this object to create a new product for this plan. We will use the product external identifier to find or create an existing product.", "properties": { "collect_shipping_address": { "description": "Whether or not to collect shipping information at checkout from the customer.", "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "The custom statement descriptor for the product i.e. WHOP*SPORTS, must be between 5 and 22 characters, contain at least one letter, and not contain any of the following characters: <, >, \\, ', \"", "type": [ "string", "null" ] }, "description": { "description": "A written description of the product.", "type": [ "string", "null" ] }, "external_identifier": { "description": "A unique ID used to find or create a product. When provided during creation, we will look for an existing product with this external identifier — if found, it will be updated; otherwise, a new product will be created.", "type": "string" }, "global_affiliate_percentage": { "description": "The percentage of the revenue that goes to the global affiliate program.", "example": 6.9, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "The status of the global affiliate program for this product.", "oneOf": [ { "$ref": "#/components/schemas/GlobalAffiliateStatuses" }, { "type": "null" } ] }, "headline": { "description": "The headline of the product.", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "The ID of the product tax code to apply to this product.", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "The URL to redirect the customer to after a purchase.", "type": [ "string", "null" ] }, "route": { "description": "The route of the product.", "type": [ "string", "null" ] }, "title": { "description": "The title of the product.", "type": "string" }, "visibility": { "description": "This product will/will not be displayed publicly - default hidden.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "The product the plan is related to. Either this or product is required.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "renewal_price": { "description": "The amount the customer is charged every billing period. Provided as a number in the specified currency. Eg: 10.43 for $10.43 USD.", "example": 6.9, "type": [ "number", "null" ] }, "title": { "description": "The title of the plan. This will be visible on the product page to customers.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "The number of free trial days added before a renewal plan.", "example": 42, "type": [ "integer", "null" ] }, "visibility": { "description": "Shows or hides the plan from public/business view.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [ "currency" ], "type": "object" } }, "required": [ "company_id", "member_id", "payment_method_id", "plan" ], "title": "CreatePaymentInputWithPlan", "type": "object" }, { "description": "Autogenerated input type of CreatePayment", "properties": { "company_id": { "description": "The ID of the company to create the payment for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "member_id": { "description": "The ID of the member to create the payment for.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata to attach to the payment.", "type": [ "object", "null" ] }, "payment_method_id": { "description": "The ID of the payment method to use for the payment. It must be connected to the Member being charged.", "example": "pmt_xxxxxxxxxxxxxx", "type": "string" }, "plan_id": { "description": "An ID of an existing plan to use for the payment.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "company_id", "member_id", "payment_method_id", "plan_id" ], "title": "CreatePaymentInputWithPlanId", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:charge", "plan:create", "access_pass:create", "access_pass:update", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "promo_code:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Create payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{id}": { "get": { "description": "Retrieves the details of an existing payment.\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`", "operationId": "retrievePayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "id", "required": true, "schema": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:basic:read", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "promo_code:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Retrieve payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{id}/fees": { "get": { "description": "Returns the list of fees associated with a specific payment, including platform fees and processing fees.\n\nRequired permissions:\n - `payment:basic:read`", "operationId": "feesPayment", "parameters": [ { "description": "The unique identifier of the payment to list fees for.", "in": "path", "name": "id", "required": true, "schema": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Fee.", "properties": { "data": { "description": "A list of nodes.", "items": { "description": "Represents a fee related to a payment", "properties": { "amount": { "description": "The value or amount to display for the fee.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the fee." }, "name": { "description": "The label to display for the fee.", "type": "string" }, "type": { "$ref": "#/components/schemas/SpecificFeeOrigins", "description": "The specific origin of the fee, if applicable." } }, "required": [ "name", "amount", "currency", "type" ], "type": "object" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List fees", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{id}/refund": { "post": { "description": "Issue a full or partial refund for a payment. The refund is processed through the original payment processor and the membership status is updated accordingly.\n\nRequired permissions:\n - `payment:manage`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`", "operationId": "refundPayment", "parameters": [ { "description": "The unique identifier of the payment to refund.", "in": "path", "name": "id", "required": true, "schema": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for RefundPayment", "properties": { "partial_amount": { "description": "The amount to refund. For multi-currency payments, this is in the charge currency (what the buyer paid). For single-currency, this is in the payment currency. If omitted, the full payment amount is refunded.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:manage", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "promo_code:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Refund payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{id}/retry": { "post": { "description": "Retry a failed or pending payment. This re-attempts the charge using the original payment method and plan details.\n\nRequired permissions:\n - `payment:manage`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`", "operationId": "retryPayment", "parameters": [ { "description": "The unique identifier of the payment to retry.", "in": "path", "name": "id", "required": true, "schema": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:manage", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "promo_code:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Retry payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{id}/void": { "post": { "description": "Void a payment that has not yet been settled. Voiding cancels the payment before it is captured by the payment processor.\n\nRequired permissions:\n - `payment:manage`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`", "operationId": "voidPayment", "parameters": [ { "description": "The unique identifier of the payment to void.", "in": "path", "name": "id", "required": true, "schema": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:manage", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read", "promo_code:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Void payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payout_accounts/{id}": { "get": { "description": "Retrieves the details of an existing payout account.\n\nRequired permissions:\n - `payout:account:read`", "operationId": "retrievePayoutAccount", "parameters": [ { "description": "The unique identifier of the payout account to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "poact_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAccount" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve payout account", "tags": [ "Payout accounts" ], "x-group-title": "Payouts" } }, "/payout_methods": { "get": { "description": "Returns a list of active payout methods configured for a company, ordered by most recently created.\n\nRequired permissions:\n - `payout:destination:read`", "operationId": "listPayoutMethod", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list payout methods for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PayoutToken.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/PayoutMethodListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "List payout methods", "tags": [ "Payout methods" ], "x-group-title": "Payouts" } }, "/payout_methods/{id}": { "get": { "description": "Retrieves the details of an existing payout method.\n\nRequired permissions:\n - `payout:destination:read`", "operationId": "retrievePayoutMethod", "parameters": [ { "description": "The unique identifier of the payout method to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "potk_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutMethod" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "Retrieve payout method", "tags": [ "Payout methods" ], "x-group-title": "Payouts" } }, "/plans": { "get": { "description": "Returns a paginated list of plans belonging to an account, with optional filtering by visibility, type, release method, and product.", "operationId": "listPlans", "parameters": [ { "description": "The unique identifier of the account to list plans for.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "The sort direction for results. Defaults to descending.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The field to sort results by. Defaults to created_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "id", "active_members_count", "created_at", "internal_notes", "expires_at" ], "type": "string" } }, { "description": "Filter to only plans matching these release methods.", "in": "query", "name": "release_methods", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter to only plans matching these visibility states.", "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter to only plans matching these billing types.", "in": "query", "name": "plan_types", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter to only plans belonging to these product identifiers.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Only return plans created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return plans created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "The number of plans to return (default and max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns plans after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of plans to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns plans before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PlanListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" }, "has_previous_page": { "type": "boolean" }, "start_cursor": { "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "plans listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "List Plans", "tags": [ "Plans" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Create a new pricing plan for a product. The plan defines the billing interval, price, and availability for customers.", "operationId": "createPlan", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account to create this plan for. Defaults to the caller's account.", "type": "string" }, "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": [ "boolean", "null" ] }, "billing_period": { "description": "The number of days between recurring charges. For example, 30 for monthly or 365 for yearly.", "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this plan.", "type": [ "object", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "type": "string" }, "custom_fields": { "description": "An array of custom field definitions to collect from customers at checkout. Omitting this field clears existing custom fields.", "items": { "properties": { "field_type": { "description": "The type of the custom field.", "enum": [ "text" ], "type": "string" }, "id": { "description": "The ID of the custom field (if being updated).", "type": "string" }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "type": "integer" }, "placeholder": { "description": "An example response displayed in the input field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A text description of the plan displayed to customers on the product page.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires and access is revoked.", "type": [ "integer", "null" ] }, "image": { "description": "An image displayed on the product page to represent this plan.", "properties": { "direct_upload_id": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "description": "The amount charged on the first purchase, in the plan's currency (e.g., 10.43 for $10.43).", "type": [ "number", "null" ] }, "internal_notes": { "description": "Private notes visible only to the business owner. Not shown to customers.", "type": [ "string", "null" ] }, "legacy_payment_method_controls": { "description": "Whether this plan uses legacy payment method controls.", "type": [ "boolean", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific plan.", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the plan. When not provided, the account's defaults apply.", "properties": { "disabled": { "items": { "type": "string" }, "type": "array" }, "enabled": { "items": { "type": "string" }, "type": "array" }, "include_platform_defaults": { "type": "boolean" } }, "type": [ "object", "null" ] }, "plan_type": { "description": "The billing type of the plan, such as one_time or renewal.", "type": "string" }, "product_id": { "description": "The unique identifier of the product to attach this plan to.", "type": "string" }, "release_method": { "description": "The method used to sell this plan (e.g., buy_now, waitlist).", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring plans, in the plan's currency.", "type": [ "number", "null" ] }, "split_pay_required_payments": { "description": "The number of installment payments required before the subscription pauses.", "type": [ "integer", "null" ] }, "stock": { "description": "The maximum number of units available for purchase. Ignored when unlimited_stock is true.", "type": [ "integer", "null" ] }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Send null to inherit the account default.", "enum": [ "mandate_challenge", "frictionless" ], "type": "string" }, "title": { "description": "The display name of the plan shown to customers on the product page.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "The number of free trial days before the first charge on a recurring plan.", "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When true, the stock field is ignored.", "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "type": "string" } }, "required": [ "product_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "plan created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing product_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "plan:create" ] } ], "summary": "Create Plan", "tags": [ "Plans" ] } }, "/plans/{id}": { "delete": { "description": "Permanently delete a plan from a product. Existing memberships on this plan will not be affected.", "operationId": "deletePlan", "responses": { "200": { "content": { "application/json": { "schema": { "description": "Always true on success.", "type": "boolean" } } }, "description": "plan deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no plan with that id" } }, "security": [ { "bearerAuth": [ "plan:delete" ] } ], "summary": "Delete Plan", "tags": [ "Plans" ] }, "get": { "description": "Retrieves the details of an existing plan.", "operationId": "retrievePlan", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "plan retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no plan with that id" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve Plan", "tags": [ "Plans" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the plan, which will look like plan_*************.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Update a plan's pricing, billing interval, visibility, stock, and other settings.", "operationId": "updatePlan", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": [ "boolean", "null" ] }, "billing_period": { "description": "The number of days between recurring charges. For example, 30 for monthly or 365 for yearly.", "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this plan.", "type": [ "object", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "type": "string" }, "custom_fields": { "description": "An array of custom field definitions to collect from customers at checkout. Omitting this field clears existing custom fields.", "items": { "properties": { "field_type": { "description": "The type of the custom field.", "enum": [ "text" ], "type": "string" }, "id": { "description": "The ID of the custom field (if being updated).", "type": "string" }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "type": "integer" }, "placeholder": { "description": "An example response displayed in the input field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A text description of the plan displayed to customers on the product page.", "type": [ "string", "null" ] }, "expiration_days": { "description": "The number of days until the membership expires and access is revoked.", "type": [ "integer", "null" ] }, "image": { "description": "An image displayed on the product page to represent this plan.", "properties": { "direct_upload_id": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "description": "The amount charged on the first purchase, in the plan's currency (e.g., 10.43 for $10.43).", "type": [ "number", "null" ] }, "internal_notes": { "description": "Private notes visible only to the business owner. Not shown to customers.", "type": [ "string", "null" ] }, "legacy_payment_method_controls": { "description": "Whether this plan uses legacy payment method controls.", "type": [ "boolean", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the plan. Included in webhook payloads for payment and membership events.", "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether to offer a retention discount when a customer attempts to cancel.", "type": [ "boolean", "null" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific plan.", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the plan. When not provided, the account's defaults apply.", "properties": { "disabled": { "items": { "type": "string" }, "type": "array" }, "enabled": { "items": { "type": "string" }, "type": "array" }, "include_platform_defaults": { "type": "boolean" } }, "type": [ "object", "null" ] }, "renewal_price": { "description": "The amount charged each billing period for recurring plans, in the plan's currency.", "type": [ "number", "null" ] }, "stock": { "description": "The maximum number of units available for purchase. Ignored when unlimited_stock is true.", "type": [ "integer", "null" ] }, "strike_through_initial_price": { "description": "A comparison price displayed with a strikethrough for the initial price.", "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "A comparison price displayed with a strikethrough for the renewal price.", "type": [ "number", "null" ] }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Send null to inherit the account default.", "enum": [ "mandate_challenge", "frictionless" ], "type": "string" }, "title": { "description": "The display name of the plan shown to customers on the product page.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "The number of free trial days before the first charge on a recurring plan.", "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When true, the stock field is ignored.", "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "plan updated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "plan:update" ] } ], "summary": "Update Plan", "tags": [ "Plans" ] } }, "/products": { "get": { "description": "Returns a paginated list of products belonging to a company, with optional filtering by type, visibility, and creation date.\n\nRequired permissions:\n - `access_pass:basic:read`", "operationId": "listProduct", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list products for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_types", "required": false, "schema": { "description": "Filter to only products matching these type classifications.", "items": { "$ref": "#/components/schemas/AccessPassTypes" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "visibilities", "required": false, "schema": { "description": "Filter to only products matching these visibility states.", "items": { "$ref": "#/components/schemas/VisibilityFilter" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to sort results by. Defaults to created_at.", "oneOf": [ { "$ref": "#/components/schemas/AccessPassOrder" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return products created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return products created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicAccessPass.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ProductListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] } ], "summary": "List products", "tags": [ "Products" ], "x-group-title": "Payins" }, "post": { "description": "Create a new product for a company. The product serves as the top-level container for plans and experiences.\n\nRequired permissions:\n - `access_pass:create`\n - `access_pass:basic:read`", "operationId": "createProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAccessPass", "properties": { "collect_shipping_address": { "description": "Whether the checkout flow collects a shipping address from the customer.", "type": [ "boolean", "null" ] }, "company_id": { "description": "The unique identifier of the company to create this product for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "custom_cta": { "description": "The call-to-action button label displayed on the product's purchase page (e.g., join, buy, subscribe).", "oneOf": [ { "$ref": "#/components/schemas/CustomCtas" }, { "type": "null" } ] }, "custom_cta_url": { "description": "A URL that the call-to-action button links to instead of the default checkout flow.", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "A custom text label that appears on the customer's bank statement. Must be 5-22 characters, contain at least one letter, and not contain <, >, \\, ', or \" characters.", "type": [ "string", "null" ] }, "description": { "description": "A written description of the product displayed on its product page.", "type": [ "string", "null" ] }, "experience_ids": { "description": "The unique identifiers of experiences to connect to this product.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "global_affiliate_percentage": { "description": "The commission rate as a percentage that affiliates earn through the global affiliate program.", "example": 6.9, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "The enrollment status of this product in the global affiliate program.", "oneOf": [ { "$ref": "#/components/schemas/GlobalAffiliateStatuses" }, { "type": "null" } ] }, "headline": { "description": "A short marketing headline displayed prominently on the product page.", "type": [ "string", "null" ] }, "member_affiliate_percentage": { "description": "The commission rate as a percentage that members earn through the member affiliate program.", "example": 6.9, "type": [ "number", "null" ] }, "member_affiliate_status": { "description": "The enrollment status of this product in the member affiliate program.", "oneOf": [ { "$ref": "#/components/schemas/GlobalAffiliateStatuses" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs to store on the product. Included in webhook payloads for payment and membership events. Max 50 keys, 500 chars per key, 5000 chars per value.", "type": [ "object", "null" ] }, "plan_options": { "description": "Configuration for an automatically generated plan to attach to this product.", "properties": { "base_currency": { "description": "The respective currency identifier for the plan.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "billing_period": { "description": "The interval at which the plan charges (renewal plans).", "example": 42, "type": [ "integer", "null" ] }, "custom_fields": { "description": "An array of custom field objects.", "items": { "properties": { "field_type": { "$ref": "#/components/schemas/CustomFieldTypes", "description": "The type of the custom field." }, "id": { "description": "The ID of the custom field (if being updated)", "type": [ "string", "null" ] }, "name": { "description": "The name of the custom field.", "type": "string" }, "order": { "description": "The order of the field.", "example": 42, "type": [ "integer", "null" ] }, "placeholder": { "description": "The placeholder value of the field.", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "type": [ "boolean", "null" ] } }, "required": [ "field_type", "name" ], "type": "object" }, "type": [ "array", "null" ] }, "initial_price": { "description": "An additional amount charged upon first purchase. Provided as a number in the specified currency. Eg: 10.43 for $10.43 USD.", "example": 6.9, "type": [ "number", "null" ] }, "plan_type": { "description": "Indicates if the plan is a one time payment or recurring.", "oneOf": [ { "$ref": "#/components/schemas/PlanTypes" }, { "type": "null" } ] }, "release_method": { "description": "The method by which the plan is released to the public.", "oneOf": [ { "$ref": "#/components/schemas/ReleaseMethod" }, { "type": "null" } ] }, "renewal_price": { "description": "The amount the customer is charged every billing period. Provided as a number in the specified currency. Eg: 10.43 for $10.43 USD.", "example": 6.9, "type": [ "number", "null" ] }, "visibility": { "description": "The visibility of the plan.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [], "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "The unique identifier of the tax classification code to apply to this product.", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "A URL to redirect the customer to after completing a purchase.", "type": [ "string", "null" ] }, "route": { "description": "The URL slug for the product's public link.", "type": [ "string", "null" ] }, "send_welcome_message": { "description": "Whether to send an automated welcome message via support chat when a user joins this product. Defaults to true.", "type": [ "boolean", "null" ] }, "title": { "description": "The display name of the product. Maximum 80 characters.", "type": "string" }, "visibility": { "description": "Whether the product is visible to customers. When set to hidden, the product is only accessible via direct link.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [ "company_id", "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "access_pass:create", "access_pass:basic:read" ] } ], "summary": "Create product", "tags": [ "Products" ], "x-group-title": "Payins" } }, "/products/{id}": { "delete": { "description": "Permanently delete a product and remove it from the company's catalog.\n\nRequired permissions:\n - `access_pass:delete`", "operationId": "deleteProduct", "parameters": [ { "description": "The unique identifier of the product to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "prod_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "access_pass:delete" ] } ], "summary": "Delete product", "tags": [ "Products" ], "x-group-title": "Payins" }, "get": { "description": "Retrieves the details of an existing product.\n\nRequired permissions:\n - `access_pass:basic:read`", "operationId": "retrieveProduct", "parameters": [ { "description": "The unique identifier or route slug of the product.", "in": "path", "name": "id", "required": true, "schema": { "example": "prod_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] } ], "summary": "Retrieve product", "tags": [ "Products" ], "x-group-title": "Payins" }, "patch": { "description": "Update a product's title, description, visibility, and other settings.\n\nRequired permissions:\n - `access_pass:update`\n - `access_pass:basic:read`", "operationId": "updateProduct", "parameters": [ { "description": "The unique identifier of the product to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "prod_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAccessPass", "properties": { "collect_shipping_address": { "description": "Whether the checkout flow collects a shipping address from the customer.", "type": [ "boolean", "null" ] }, "custom_cta": { "description": "The call-to-action button label displayed on the product's purchase page (e.g., join, buy, subscribe).", "oneOf": [ { "$ref": "#/components/schemas/CustomCtas" }, { "type": "null" } ] }, "custom_cta_url": { "description": "A URL that the call-to-action button links to instead of the default checkout flow.", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "A custom text label that appears on the customer's bank statement. Must be 5-22 characters, contain at least one letter, and not contain <, >, \\, ', or \" characters.", "type": [ "string", "null" ] }, "description": { "description": "A written description of the product displayed on its product page.", "type": [ "string", "null" ] }, "gallery_images": { "description": "The gallery images for the product.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "global_affiliate_percentage": { "description": "The commission rate as a percentage that affiliates earn through the global affiliate program.", "example": 6.9, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "The enrollment status of this product in the global affiliate program.", "oneOf": [ { "$ref": "#/components/schemas/GlobalAffiliateStatuses" }, { "type": "null" } ] }, "headline": { "description": "A short marketing headline displayed prominently on the product page.", "type": [ "string", "null" ] }, "member_affiliate_percentage": { "description": "The commission rate as a percentage that members earn through the member affiliate program.", "example": 6.9, "type": [ "number", "null" ] }, "member_affiliate_status": { "description": "The enrollment status of this product in the member affiliate program.", "oneOf": [ { "$ref": "#/components/schemas/GlobalAffiliateStatuses" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs to store on the product. Included in webhook payloads for payment and membership events. Max 50 keys, 500 chars per key, 5000 chars per value.", "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "The unique identifier of the tax classification code to apply to this product.", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "A URL to redirect the customer to after completing a purchase.", "type": [ "string", "null" ] }, "route": { "description": "The URL slug for the product's public link.", "type": [ "string", "null" ] }, "send_welcome_message": { "description": "Whether to send an automated welcome message via support chat when a user joins this product.", "type": [ "boolean", "null" ] }, "store_page_config": { "description": "Layout and display configuration for this product on the company's store page.", "properties": { "custom_cta": { "description": "Custom call-to-action text for the product's store page.", "type": [ "string", "null" ] }, "show_price": { "description": "Whether or not to show the price on the product's store page.", "type": [ "boolean", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "title": { "description": "The display name of the product. Maximum 80 characters.", "type": [ "string", "null" ] }, "visibility": { "description": "Whether the product is visible to customers. When set to hidden, the product is only accessible via direct link.", "oneOf": [ { "$ref": "#/components/schemas/Visibility" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "access_pass:update", "access_pass:basic:read" ] } ], "summary": "Update product", "tags": [ "Products" ], "x-group-title": "Payins" } }, "/promo_codes": { "get": { "description": "Returns a paginated list of promo codes belonging to a company, with optional filtering by product, plan, and status.\n\nRequired permissions:\n - `promo_code:basic:read`\n - `access_pass:basic:read`", "operationId": "listPromoCode", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list promo codes for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter to only promo codes scoped to these product identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "plan_ids", "required": false, "schema": { "description": "Filter to only promo codes scoped to these plan identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "description": "Filter to only promo codes matching this status.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeStatus" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return promo codes created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return promo codes created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PromoCode.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/PromoCodeListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "promo_code:basic:read", "access_pass:basic:read" ] } ], "summary": "List promo codes", "tags": [ "Promo codes" ], "x-group-title": "Payins" }, "post": { "description": "Create a new promo code that applies a discount at checkout. Can be scoped to specific products or plans.\n\nRequired permissions:\n - `promo_code:create`\n - `access_pass:basic:read`", "operationId": "createPromoCode", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreatePromoCode", "properties": { "amount_off": { "description": "The discount amount. When promo_type is percentage, this is the percent off (e.g., 20 for 20% off). When promo_type is flat_amount, this is the currency amount off (e.g., 10.00 for $10.00 off).", "example": 6.9, "type": "number" }, "base_currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the promo code discount." }, "churned_users_only": { "description": "Whether to restrict this promo code to only users who have previously churned from the company.", "type": [ "boolean", "null" ] }, "code": { "description": "The alphanumeric code customers enter at checkout to apply the discount.", "type": "string" }, "company_id": { "description": "The unique identifier of the company to create this promo code for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "existing_memberships_only": { "description": "Whether this promo code can only be applied to existing memberships, such as for cancellation retention offers.", "type": [ "boolean", "null" ] }, "expires_at": { "description": "The datetime when the promo code expires and can no longer be used. Null means it never expires.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "new_users_only": { "description": "Whether to restrict this promo code to only users who have never purchased from the company before.", "type": "boolean" }, "one_per_customer": { "description": "Whether each customer can only use this promo code once.", "type": [ "boolean", "null" ] }, "plan_ids": { "description": "The identifiers of plans this promo code applies to. When product_id is also provided, only plans attached to that product are included.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] }, "product_id": { "description": "The identifier of the product to scope this promo code to. When provided, the promo code only applies to plans attached to this product.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "promo_duration_months": { "description": "The number of billing months the discount remains active. For example, 3 means the discount applies to the first 3 billing cycles.", "example": 42, "type": "integer" }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The discount type, either percentage or flat_amount." }, "stock": { "description": "The maximum number of times this promo code can be used. Ignored when unlimited_stock is true.", "example": 42, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the promo code can be used an unlimited number of times.", "type": [ "boolean", "null" ] } }, "required": [ "amount_off", "base_currency", "code", "company_id", "new_users_only", "promo_duration_months", "promo_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "promo_code:create", "access_pass:basic:read" ] } ], "summary": "Create promo code", "tags": [ "Promo codes" ], "x-group-title": "Payins" } }, "/promo_codes/{id}": { "delete": { "description": "Archive a promo code, preventing it from being used in future checkouts. Existing memberships are not affected.\n\nRequired permissions:\n - `promo_code:delete`", "operationId": "deletePromoCode", "parameters": [ { "description": "The unique identifier of the promo code to archive.", "in": "path", "name": "id", "required": true, "schema": { "example": "promo_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "promo_code:delete" ] } ], "summary": "Delete promo code", "tags": [ "Promo codes" ], "x-group-title": "Payins" }, "get": { "description": "Retrieves the details of an existing promo code.\n\nRequired permissions:\n - `promo_code:basic:read`\n - `access_pass:basic:read`", "operationId": "retrievePromoCode", "parameters": [ { "description": "The unique identifier of the promo code.", "in": "path", "name": "id", "required": true, "schema": { "example": "promo_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "promo_code:basic:read", "access_pass:basic:read" ] } ], "summary": "Retrieve promo code", "tags": [ "Promo codes" ], "x-group-title": "Payins" }, "patch": { "description": "Update whether a promo code can be used at checkout.\n\nRequired permissions:\n - `promo_code:update`\n - `access_pass:basic:read`", "operationId": "updatePromoCode", "parameters": [ { "description": "The unique identifier of the promo code to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "promo_xxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdatePromoCode", "properties": { "status": { "$ref": "#/components/schemas/PromoCodeUpdateStatus", "description": "The status to apply to the promo code." } }, "required": [ "status" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "promo_code:update", "access_pass:basic:read" ] } ], "summary": "Update promo code", "tags": [ "Promo codes" ], "x-group-title": "Payins" } }, "/reactions": { "get": { "description": "Returns a paginated list of emoji reactions on a specific message or forum post, sorted by most recent.\n\nRequired permissions:\n - `chat:read`", "operationId": "listReaction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "resource_id", "required": true, "schema": { "description": "The unique identifier of the message or forum post to list reactions for.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Reaction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ReactionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "List reactions", "tags": [ "Reactions" ], "x-group-title": "Engagement" }, "post": { "description": "Add an emoji reaction or poll vote to a message or forum post. In forums, the reaction is always a like.\n\nRequired permissions:\n - `chat:read`", "operationId": "createReaction", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateReaction", "properties": { "emoji": { "description": "The emoji to react with, in shortcode or unicode format. For example, ':heart:' or a unicode emoji. Ignored in forums where reactions are always likes.", "type": [ "string", "null" ] }, "poll_option_id": { "description": "The unique identifier of a poll option to vote for. Only valid when the target message or post contains a poll.", "type": [ "string", "null" ] }, "resource_id": { "description": "The unique identifier of the message or forum post to react to.", "type": "string" } }, "required": [ "resource_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "Create reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" } }, "/reactions/{id}": { "delete": { "description": "Remove an emoji reaction from a message or forum post. Only the reaction author or a channel admin can remove a reaction.\n\nRequired permissions:\n - `chat:read`", "operationId": "deleteReaction", "parameters": [ { "description": "The unique identifier of the reaction to remove, or the identifier of the message or forum post to remove a reaction from. When passing a message or post ID, you must also provide the emoji argument.", "in": "path", "name": "id", "required": true, "schema": { "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "emoji", "required": false, "schema": { "description": "The emoji to remove, in shortcode or unicode format. For example, ':heart:' or a unicode emoji. Required when the id refers to a message or post instead of a reaction.", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "Delete reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing reaction.\n\nRequired permissions:\n - `chat:read`", "operationId": "retrieveReaction", "parameters": [ { "description": "The unique identifier of the reaction to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "Retrieve reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" } }, "/refunds": { "get": { "description": "Returns a paginated list of refunds, with optional filtering by payment, company, user, and creation date.\n\nRequired permissions:\n - `payment:basic:read`", "operationId": "listRefund", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "payment_id", "required": false, "schema": { "description": "Filter refunds to only those associated with this specific payment.", "example": "pay_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Filter refunds to only those belonging to this company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter refunds to only those associated with this specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return refunds created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return refunds created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Refund.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/RefundListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List refunds", "tags": [ "Refunds" ], "x-group-title": "Payins" } }, "/refunds/{id}": { "get": { "description": "Retrieves the details of an existing refund.\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`", "operationId": "retrieveRefund", "parameters": [ { "description": "The unique identifier of the refund.", "in": "path", "name": "id", "required": true, "schema": { "example": "rf_xxxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:basic:read", "plan:basic:read", "access_pass:basic:read", "member:email:read", "member:basic:read", "member:phone:read" ] } ], "summary": "Retrieve refund", "tags": [ "Refunds" ], "x-group-title": "Payins" } }, "/resolution_center_cases": { "get": { "description": "Returns a paginated list of resolution center cases, with optional filtering by company, status, and creation date.\n\nRequired permissions:\n - `payment:resolution_center_case:read`", "operationId": "listResolutionCenterCase", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list resolution center cases for.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "statuses", "required": false, "schema": { "description": "Filter by resolution center case status.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return cases created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return cases created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicResolution.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "List resolution center cases", "tags": [ "Resolution center cases" ], "x-group-title": "Payins" } }, "/resolution_center_cases/{id}": { "get": { "description": "Retrieves the details of an existing resolution center case.\n\nRequired permissions:\n - `payment:resolution_center_case:read`", "operationId": "retrieveResolutionCenterCase", "parameters": [ { "description": "The unique identifier of the resolution center case.", "in": "path", "name": "id", "required": true, "schema": { "example": "reso_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "Retrieve resolution center case", "tags": [ "Resolution center cases" ], "x-group-title": "Payins" } }, "/reviews": { "get": { "description": "Returns a paginated list of customer reviews for a specific product, with optional filtering by star rating and creation date.", "operationId": "listReview", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": true, "schema": { "description": "The unique identifier of the product to list reviews for.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "min_stars", "required": false, "schema": { "description": "The minimum star rating to include in results, from 1 to 5 inclusive.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "max_stars", "required": false, "schema": { "description": "The maximum star rating to include in results, from 1 to 5 inclusive.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return reviews created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return reviews created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Review.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ReviewListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List reviews", "tags": [ "Reviews" ], "x-group-title": "CRM" } }, "/reviews/{id}": { "get": { "description": "Retrieves the details of an existing review.", "operationId": "retrieveReview", "parameters": [ { "description": "The unique identifier of the review to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "rev_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve review", "tags": [ "Reviews" ], "x-group-title": "CRM" } }, "/setup_intents": { "get": { "description": "Returns a paginated list of setup intents for a company, with optional filtering by creation date. A setup intent securely collects and stores a member's payment method for future use without charging them immediately.\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`", "operationId": "listSetupIntent", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list setup intents for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for ordering results, either ascending or descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return setup intents created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return setup intents created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for SetupIntent.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/SetupIntentListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:setup_intent:read", "member:basic:read", "member:email:read" ] } ], "summary": "List setup intents", "tags": [ "Setup intents" ], "x-group-title": "Payins" } }, "/setup_intents/{id}": { "get": { "description": "Retrieves the details of an existing setup intent.\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`", "operationId": "retrieveSetupIntent", "parameters": [ { "description": "The unique identifier of the setup intent.", "in": "path", "name": "id", "required": true, "schema": { "example": "sint_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntent" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:setup_intent:read", "member:basic:read", "member:email:read" ] } ], "summary": "Retrieve setup intent", "tags": [ "Setup intents" ], "x-group-title": "Payins" } }, "/shipments": { "get": { "description": "Returns a paginated list of shipments, with optional filtering by payment, company, or user.\n\nRequired permissions:\n - `shipment:basic:read`\n - `payment:basic:read`", "operationId": "listShipment", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "payment_id", "required": false, "schema": { "description": "Filter shipments to only those associated with this specific payment.", "example": "pay_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Filter shipments to only those belonging to this company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter shipments to only those for this specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Shipment.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ShipmentListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "shipment:basic:read", "payment:basic:read" ] } ], "summary": "List shipments", "tags": [ "Shipments" ], "x-group-title": "CRM" }, "post": { "description": "Create a new shipment with a tracking code for a specific payment within a company.\n\nRequired permissions:\n - `shipment:create`\n - `payment:basic:read`", "operationId": "createShipment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateShipment", "properties": { "company_id": { "description": "The unique identifier of the company to create the shipment for, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "payment_id": { "description": "The unique identifier of the payment to associate the shipment with.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "tracking_code": { "description": "The carrier tracking code for the shipment, such as a USPS, UPS, or FedEx tracking number.", "type": "string" } }, "required": [ "company_id", "payment_id", "tracking_code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "shipment:create", "payment:basic:read" ] } ], "summary": "Create shipment", "tags": [ "Shipments" ], "x-group-title": "CRM" } }, "/shipments/{id}": { "get": { "description": "Retrieves the details of an existing shipment.\n\nRequired permissions:\n - `shipment:basic:read`\n - `payment:basic:read`", "operationId": "retrieveShipment", "parameters": [ { "description": "The unique identifier of the shipment to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "ship_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "shipment:basic:read", "payment:basic:read" ] } ], "summary": "Retrieve shipment", "tags": [ "Shipments" ], "x-group-title": "CRM" } }, "/stats/describe": { "get": { "description": "Describe available stats schema. Without resource returns root nodes and metrics. With resource returns node columns, associations, and available metrics.\n\nRequired permissions:\n - `stats:read`", "operationId": "describeStats", "parameters": [ { "explode": true, "in": "query", "name": "resource", "required": false, "schema": { "description": "Resource path using : as separator (e.g., 'receipts', 'payments:membership', 'receipts:gross_revenue').", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "Root schema description showing available nodes, views, and metrics.", "properties": { "debug": { "description": "Debug information.", "properties": { "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] } }, "required": [ "request_id" ], "type": [ "object", "null" ] }, "metrics": { "description": "Available metrics.", "items": { "description": "A metric available for querying.", "properties": { "name": { "description": "The metric name.", "type": "string" }, "node_path": { "description": "The node path this metric operates on.", "type": "string" }, "supported_engines": { "description": "Query engines that support this metric.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" } }, "required": [ "name", "node_path", "supported_engines" ], "type": "object" }, "type": "array" }, "nodes": { "description": "Available root nodes.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "typename": { "const": "DescribeRoot", "description": "The typename of this object", "type": "string" }, "views": { "description": "Available API resource views.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" } }, "required": [ "typename", "nodes", "views", "metrics", "debug" ], "title": "DescribeRoot", "type": [ "object", "null" ] }, { "description": "Description of a node (model) including its columns and associations.", "properties": { "associations": { "description": "Available associations or child paths.", "items": { "description": "An association or child path available for navigation.", "properties": { "event_name": { "description": "The event name (for event type).", "type": [ "string", "null" ] }, "model": { "description": "The associated model class name (for model associations).", "type": [ "string", "null" ] }, "name": { "description": "The association name.", "type": "string" }, "path": { "description": "The full path (for event associations).", "type": [ "string", "null" ] }, "type": { "description": "The type (belongs_to, has_many, has_one, event, namespace).", "type": "string" } }, "required": [ "name", "type", "model", "path", "event_name" ], "type": "object" }, "type": "array" }, "columns": { "description": "Available columns.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "debug": { "description": "Debug information.", "properties": { "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] } }, "required": [ "request_id" ], "type": [ "object", "null" ] }, "engine": { "description": "The query engine being used.", "type": "string" }, "metrics": { "description": "Available metrics for this node.", "items": { "description": "A metric available for querying.", "properties": { "name": { "description": "The metric name.", "type": "string" }, "node_path": { "description": "The node path this metric operates on.", "type": "string" }, "supported_engines": { "description": "Query engines that support this metric.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" } }, "required": [ "name", "node_path", "supported_engines" ], "type": "object" }, "type": "array" }, "node": { "description": "The node path being described.", "type": "string" }, "sample": { "description": "Sample data rows.", "items": { "additionalProperties": true, "description": "Represents untyped JSON", "type": "object" }, "type": [ "array", "null" ] }, "sortable_columns": { "description": "Columns that can be used for sorting.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "typename": { "const": "DescribeNode", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "node", "engine", "columns", "sortable_columns", "associations", "metrics", "sample", "debug" ], "title": "DescribeNode", "type": [ "object", "null" ] }, { "description": "Description of a metric including its configuration and SQL.", "properties": { "breakdownable_columns": { "description": "Columns that can be used for breakdowns.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "debug": { "description": "Debug information.", "properties": { "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] } }, "required": [ "request_id" ], "type": [ "object", "null" ] }, "engine": { "description": "The query engine being used.", "type": "string" }, "filterable_columns": { "description": "Columns that can be used for filtering.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "metric": { "description": "The metric name.", "type": "string" }, "node": { "description": "The node path this metric operates on.", "type": "string" }, "sql": { "description": "The generated SQL query.", "type": [ "string", "null" ] }, "supported_engines": { "description": "Query engines that support this metric.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "timestamp_column": { "description": "The timestamp column used for time filtering.", "type": "string" }, "typename": { "const": "DescribeMetric", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "metric", "node", "engine", "timestamp_column", "supported_engines", "filterable_columns", "breakdownable_columns", "sql", "debug" ], "title": "DescribeMetric", "type": [ "object", "null" ] }, { "description": "Description of an API resource view including its columns and associations.", "properties": { "associations": { "description": "Available associations.", "items": { "description": "An association or child path available for navigation.", "properties": { "event_name": { "description": "The event name (for event type).", "type": [ "string", "null" ] }, "model": { "description": "The associated model class name (for model associations).", "type": [ "string", "null" ] }, "name": { "description": "The association name.", "type": "string" }, "path": { "description": "The full path (for event associations).", "type": [ "string", "null" ] }, "type": { "description": "The type (belongs_to, has_many, has_one, event, namespace).", "type": "string" } }, "required": [ "name", "type", "model", "path", "event_name" ], "type": "object" }, "type": "array" }, "columns": { "description": "Available columns.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "debug": { "description": "Debug information.", "properties": { "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] } }, "required": [ "request_id" ], "type": [ "object", "null" ] }, "engine": { "description": "The query engine being used.", "type": "string" }, "metrics": { "description": "Available metrics.", "items": { "description": "A metric available for querying.", "properties": { "name": { "description": "The metric name.", "type": "string" }, "node_path": { "description": "The node path this metric operates on.", "type": "string" }, "supported_engines": { "description": "Query engines that support this metric.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" } }, "required": [ "name", "node_path", "supported_engines" ], "type": "object" }, "type": "array" }, "model": { "description": "The underlying model class.", "type": "string" }, "resource": { "description": "The API resource name.", "type": "string" }, "sample": { "description": "Sample data rows.", "items": { "additionalProperties": true, "description": "Represents untyped JSON", "type": "object" }, "type": [ "array", "null" ] }, "sortable_columns": { "description": "Columns that can be used for sorting.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "typename": { "const": "DescribeView", "description": "The typename of this object", "type": "string" }, "view": { "description": "The view name being described.", "type": "string" } }, "required": [ "typename", "view", "resource", "model", "engine", "columns", "sortable_columns", "associations", "metrics", "sample", "debug" ], "title": "DescribeView", "type": [ "object", "null" ] } ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "stats:read" ] } ], "summary": "Describe stats", "tags": [ "Stats" ], "x-group-title": "Stats" } }, "/stats/metric": { "get": { "description": "Query an aggregated metric. Returns data grouped by period with optional breakdowns.\n\nRequired permissions:\n - `stats:read`", "operationId": "metricStats", "parameters": [ { "explode": true, "in": "query", "name": "resource", "required": true, "schema": { "description": "Metric resource using : as separator (e.g., 'receipts:gross_revenue', 'members:new_users').", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "granularity", "required": false, "schema": { "description": "Time granularity (daily, weekly, monthly).", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "breakdowns", "required": false, "schema": { "description": "Columns to break down the metric by.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "filters", "required": false, "schema": { "additionalProperties": true, "description": "Key-value pairs to filter the data.", "type": [ "object", "null" ] }, "style": "deepObject" }, { "explode": true, "in": "query", "name": "time_zone", "required": false, "schema": { "description": "IANA timezone for period bucketing (e.g. 'America/New_York'). Defaults to UTC. Only applies to ClickHouse metrics.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "from", "required": false, "schema": { "description": "Start of time range (unix timestamp).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "to", "required": false, "schema": { "description": "End of time range (unix timestamp).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Result from a stats query (raw, metric, or SQL).", "properties": { "columns": { "description": "Column names in the order they appear in each data row.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "data": { "description": "Array of data rows, where each row is an array of values matching the columns order.", "items": { "additionalProperties": true, "description": "Represents untyped JSON", "type": "object" }, "type": [ "array", "null" ] }, "debug": { "description": "Debug information including engine and SQL.", "properties": { "engine": { "description": "The query engine used.", "type": [ "string", "null" ] }, "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] }, "sql": { "description": "The generated SQL query (with IDs sanitized).", "type": [ "string", "null" ] } }, "required": [ "engine", "request_id", "sql" ], "type": [ "object", "null" ] }, "node": { "description": "The node path that was queried.", "type": [ "string", "null" ] }, "pagination": { "description": "Pagination information.", "properties": { "next_cursor": { "description": "Cursor for the next page of results.", "type": [ "string", "null" ] } }, "required": [ "next_cursor" ], "type": [ "object", "null" ] }, "typename": { "const": "Result", "description": "The typename of this object", "type": "string" } }, "required": [ "columns", "data", "debug", "node", "pagination", "typename" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "stats:read" ] } ], "summary": "Metric stats", "tags": [ "Stats" ], "x-group-title": "Stats" } }, "/stats/raw": { "get": { "description": "Query raw data from a resource. Returns paginated rows with all columns.\n\nRequired permissions:\n - `stats:read`", "operationId": "rawStats", "parameters": [ { "explode": true, "in": "query", "name": "resource", "required": true, "schema": { "description": "Resource path using : as separator (e.g., 'members', 'payments:membership').", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "from", "required": false, "schema": { "description": "Start of time range (unix timestamp).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "to", "required": false, "schema": { "description": "End of time range (unix timestamp).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "description": "Number of records to return (max 10000).", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "cursor", "required": false, "schema": { "description": "Pagination cursor for next page.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "sort", "required": false, "schema": { "description": "Column to sort by.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "sort_direction", "required": false, "schema": { "description": "Sort direction (asc or desc).", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Result from a stats query (raw, metric, or SQL).", "properties": { "columns": { "description": "Column names in the order they appear in each data row.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "data": { "description": "Array of data rows, where each row is an array of values matching the columns order.", "items": { "additionalProperties": true, "description": "Represents untyped JSON", "type": "object" }, "type": [ "array", "null" ] }, "debug": { "description": "Debug information including engine and SQL.", "properties": { "engine": { "description": "The query engine used.", "type": [ "string", "null" ] }, "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] }, "sql": { "description": "The generated SQL query (with IDs sanitized).", "type": [ "string", "null" ] } }, "required": [ "engine", "request_id", "sql" ], "type": [ "object", "null" ] }, "node": { "description": "The node path that was queried.", "type": [ "string", "null" ] }, "pagination": { "description": "Pagination information.", "properties": { "next_cursor": { "description": "Cursor for the next page of results.", "type": [ "string", "null" ] } }, "required": [ "next_cursor" ], "type": [ "object", "null" ] } }, "required": [ "columns", "data", "debug", "node", "pagination" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "stats:read" ] } ], "summary": "Raw stats", "tags": [ "Stats" ], "x-group-title": "Stats" } }, "/stats/schema": { "get": { "description": "Returns the full taxonomy of reporting categories, groupings, and line categories with descriptions. Use this to discover valid filter values for the time-series endpoint. No authentication required.", "operationId": "retrieveStatsSchema", "parameters": [ { "description": "The stats resource to describe. Currently only `wallet` is supported.", "in": "query", "name": "resource_type", "required": true, "schema": { "enum": [ "wallet" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groupings": { "items": { "properties": { "line_categories": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "name", "line_categories" ], "type": "object" }, "type": "array" }, "line_categories": { "items": { "properties": { "description": { "type": "string" }, "grouping": { "type": "string" }, "key": { "type": "string" }, "reporting_categories": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "description", "grouping", "reporting_categories" ], "type": "object" }, "type": "array" }, "reporting_categories": { "items": { "properties": { "line_categories": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "name", "line_categories" ], "type": "object" }, "type": "array" } }, "required": [ "reporting_categories", "groupings", "line_categories" ], "type": "object" } } }, "description": "stats schema retrieved" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "resource_type is missing or invalid" } }, "summary": "Retrieve Stats Schema", "tags": [ "Stats" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/stats/sql": { "get": { "description": "Run custom SQL against a scoped resource. Use SCOPED_DATA as the table name.\n\nRequired permissions:\n - `stats:read`", "operationId": "sqlStats", "parameters": [ { "explode": true, "in": "query", "name": "resource", "required": true, "schema": { "description": "Resource path using : as separator (e.g., 'receipts', 'payments:membership').", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "sql", "required": true, "schema": { "description": "SQL query. Use SCOPED_DATA as the table name.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "from", "required": false, "schema": { "description": "Start of time range (unix timestamp).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "to", "required": false, "schema": { "description": "End of time range (unix timestamp).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "description": "Number of records to return (max 10000).", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "cursor", "required": false, "schema": { "description": "Pagination cursor for next page.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "sort", "required": false, "schema": { "description": "Column to sort by.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "sort_direction", "required": false, "schema": { "description": "Sort direction (asc or desc).", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Result from a stats query (raw, metric, or SQL).", "properties": { "columns": { "description": "Column names in the order they appear in each data row.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "data": { "description": "Array of data rows, where each row is an array of values matching the columns order.", "items": { "additionalProperties": true, "description": "Represents untyped JSON", "type": "object" }, "type": [ "array", "null" ] }, "debug": { "description": "Debug information including engine and SQL.", "properties": { "engine": { "description": "The query engine used.", "type": [ "string", "null" ] }, "request_id": { "description": "Unique request identifier for debugging.", "type": [ "string", "null" ] }, "sql": { "description": "The generated SQL query (with IDs sanitized).", "type": [ "string", "null" ] } }, "required": [ "engine", "request_id", "sql" ], "type": [ "object", "null" ] }, "node": { "description": "The node path that was queried.", "type": [ "string", "null" ] }, "pagination": { "description": "Pagination information.", "properties": { "next_cursor": { "description": "Cursor for the next page of results.", "type": [ "string", "null" ] } }, "required": [ "next_cursor" ], "type": [ "object", "null" ] }, "typename": { "const": "Result", "description": "The typename of this object", "type": "string" } }, "required": [ "columns", "data", "debug", "node", "pagination", "typename" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "stats:read" ] } ], "summary": "Sql stats", "tags": [ "Stats" ], "x-group-title": "Stats" } }, "/stats/time_series": { "get": { "description": "Returns an aggregated financial time series from the ledger: total amount and line count per period, optionally filtered by reporting category, grouping, or line category. The wallet is resolved from the caller's auth context, or from `account_id` when given. External API keys are scoped to the `net_activity` reporting category.", "operationId": "listStatsTimeSeries", "parameters": [ { "description": "The stats resource to query. Currently only `wallet` is supported.", "in": "query", "name": "resource_type", "required": true, "schema": { "enum": [ "wallet" ], "type": "string" } }, { "description": "Start of the date range (ISO 8601, e.g. 2025-01-01).", "in": "query", "name": "from", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "End of the date range (ISO 8601, e.g. 2025-12-31).", "in": "query", "name": "to", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Period size for each data point. Defaults to `month`.", "in": "query", "name": "group_by", "required": false, "schema": { "enum": [ "day", "week", "month" ], "type": "string" } }, { "description": "The business or user account ID whose wallet should be queried. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Restricts the series to one reporting category. See the stats schema endpoint for valid values.", "in": "query", "name": "reporting_category", "required": false, "schema": { "type": "string" } }, { "description": "Filters to one or more groupings. See the stats schema endpoint for valid values.", "in": "query", "name": "grouping", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filters to one or more line categories. See the stats schema endpoint for valid values.", "in": "query", "name": "line_category", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filters to ledger lines denominated in this currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Converts amounts into this currency.", "in": "query", "name": "convert_currency", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone used for period boundaries (e.g. America/New_York). Defaults to UTC.", "in": "query", "name": "timezone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "amount": { "description": "Decimal amount serialized as a string.", "type": "string" }, "currency": { "description": "Rows are split per currency.", "type": "string" }, "line_count": { "type": "integer" }, "period": { "description": "Start of the period (e.g. 2025-01-01 00:00:00).", "type": "string" } }, "required": [ "period", "currency", "amount", "line_count" ], "type": "object" }, "type": "array" }, "metadata": { "properties": { "account_id": { "type": "string" }, "base_reporting_scope": { "type": "string" }, "convert_currency": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" }, "from": { "type": "string" }, "group_by": { "enum": [ "day", "week", "month" ], "type": "string" }, "grouping": { "items": { "type": "string" }, "type": "array" }, "line_category": { "items": { "type": "string" }, "type": "array" }, "reporting_category": { "type": "string" }, "timezone": { "type": "string" }, "to": { "type": "string" }, "wallet_id": { "type": "string" } }, "required": [ "from", "to", "group_by", "timezone" ], "type": "object" } }, "required": [ "data", "metadata" ], "type": "object" } } }, "description": "time series listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "date range is missing or invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Time Series", "tags": [ "Stats" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/support_channels": { "get": { "description": "Returns a paginated list of support channels for a specific company, with optional filtering by resolution status and custom sorting.\n\nRequired permissions:\n - `support_chat:read`", "operationId": "listSupportChannel", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "The unique identifier of the company to list support channels for. Includes channels of child companies. When omitted, returns support channels across all companies the user has access to.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "view", "required": false, "schema": { "description": "Filter support channels by the authenticated user's role. Defaults to admin. When the caller is a company API key (no user), only admin-visible channels are returned.", "oneOf": [ { "$ref": "#/components/schemas/SupportChannelView" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "open", "required": false, "schema": { "description": "Whether to filter by open or resolved support channels. Set to true to only return channels awaiting a response, or false for resolved channels.", "type": [ "boolean", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for the results. Use 'asc' for oldest first or 'desc' for newest first.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The field to sort the support channels by, such as creation date or last message time.", "oneOf": [ { "$ref": "#/components/schemas/MessageChannelOrder" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/SupportChannelListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "support_chat:read" ] } ], "summary": "List support channels", "tags": [ "Support channels" ], "x-group-title": "Engagement" }, "post": { "description": "Open a new support channel between a company team member and a customer. Returns the existing channel if one already exists for that user.\n\nRequired permissions:\n - `support_chat:create`", "operationId": "createSupportChannel", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateSupportChatForUser", "properties": { "company_id": { "description": "The unique identifier of the company to create the support channel in.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "custom_name": { "description": "Optional custom display name for the support channel.", "type": [ "string", "null" ] }, "user_id": { "description": "The user ID (e.g. 'user_xxxxx') or username of the customer to open a support channel for.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "company_id", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "support_chat:create" ] } ], "summary": "Create support channel", "tags": [ "Support channels" ], "x-group-title": "Engagement" } }, "/support_channels/{id}": { "get": { "description": "Retrieves the details of an existing support channel.\n\nRequired permissions:\n - `support_chat:read`", "operationId": "retrieveSupportChannel", "parameters": [ { "description": "The unique identifier of the support channel to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve support channel", "tags": [ "Support channels" ], "x-group-title": "Engagement" } }, "/swaps": { "get": { "description": "Lists the account's swaps — currently its in-flight or most recent swap, so zero or one rows.", "operationId": "listSwaps", "parameters": [ { "description": "Business or user account ID (biz_* / user_*).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_id": { "type": "string" }, "error": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "object": { "enum": [ "swap" ], "type": "string" }, "status": { "type": "string" }, "tx_hashes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "object", "id", "account_id", "status", "tx_hashes" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "swaps listed" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the crypto-wallet scope" } }, "security": [ { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "List Swaps", "tags": [ "Swaps" ] }, "post": { "description": "Executes a swap from the account's wallet. Runs asynchronously — poll GET /swaps/{id} for status.", "operationId": "createSwap", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Business or user account ID (biz_* / user_*).", "type": "string" }, "amount": { "description": "Input token amount.", "type": "string" }, "from_chain": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "from_token": { "description": "Source token, by contract address or ticker symbol (e.g. \"USDT\").", "type": "string" }, "slippage_bps": { "nullable": true, "type": "integer" }, "to_chain": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "to_token": { "description": "Destination token, by contract address or ticker symbol (e.g. \"XAUT\").", "type": "string" } }, "required": [ "account_id", "amount", "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "type": "string" }, "amount_out_expected": { "type": "string" }, "amount_out_min": { "type": "string" }, "id": { "description": "Swap ID — poll GET /swaps/{id} for status.", "type": "string" }, "object": { "enum": [ "swap" ], "type": "string" }, "rate": { "type": "string" }, "status": { "type": "string" }, "to_chain": { "type": "string" } }, "required": [ "object", "id", "account_id", "status" ], "type": "object" } } }, "description": "swap created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the crypto-wallet scope" } }, "security": [ { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "Create Swap", "tags": [ "Swaps" ] } }, "/swaps/quote": { "post": { "description": "Returns a stateless swap price preview. No funds move and nothing is persisted.", "operationId": "createSwapQuote", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Input token amount.", "type": "string" }, "from_address": { "nullable": true, "type": "string" }, "from_chain": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "from_token": { "description": "Source token, by contract address or ticker symbol (e.g. \"USDT\").", "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "slippage_bps": { "nullable": true, "type": "integer" }, "to_address": { "nullable": true, "type": "string" }, "to_chain": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "to_token": { "description": "Destination token, by contract address or ticker symbol (e.g. \"XAUT\").", "type": "string" } }, "required": [ "amount", "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount_in": { "type": "string" }, "amount_out": { "type": "string" }, "amount_out_min": { "type": "string" }, "bridge_fee": { "nullable": true, "type": "string" }, "estimated_duration_seconds": { "nullable": true, "type": "integer" }, "fee_bps": { "type": "integer" }, "from_address": { "nullable": true, "type": "string" }, "from_token": { "additionalProperties": true, "type": "object" }, "metadata": { "additionalProperties": true, "type": "object" }, "object": { "enum": [ "swap_quote" ], "type": "string" }, "rate": { "type": "string" }, "requires_token_approval": { "nullable": true, "type": "boolean" }, "to_address": { "nullable": true, "type": "string" }, "to_token": { "additionalProperties": true, "type": "object" } }, "required": [ "object", "amount_in", "amount_out", "rate", "fee_bps", "from_token", "to_token", "metadata" ], "type": "object" } } }, "description": "swap quote created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" } }, "security": [], "summary": "Create Swap Quote", "tags": [ "Swaps" ] } }, "/swaps/{id}": { "get": { "description": "Returns the status of a specific swap, by the id returned from POST /swaps.", "operationId": "retrieveSwap", "parameters": [ { "description": "Swap ID returned from POST /swaps.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "type": "string" }, "error": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "object": { "enum": [ "swap" ], "type": "string" }, "status": { "type": "string" }, "tx_hashes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "object", "id", "account_id", "status", "tx_hashes" ], "type": "object" } } }, "description": "swap status retrieved" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "swap id is invalid" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the crypto-wallet scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "swap does not exist" } }, "security": [ { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "Retrieve Swap", "tags": [ "Swaps" ] } }, "/topups": { "post": { "description": "Add funds to a company's platform balance by charging a stored payment method. Top-ups have no fees or taxes and do not count as revenue.\n\nRequired permissions:\n - `payment:charge`", "operationId": "createTopup", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateTopup", "properties": { "amount": { "description": "The amount to add to the balance in the specified currency. For example, 50.00 for $50.00 USD.", "example": 6.9, "type": "number" }, "company_id": { "description": "The unique identifier of the company to add funds to, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency for the top-up amount, such as 'usd'." }, "payment_method_id": { "description": "The unique identifier of the stored payment method to charge for the top-up.", "example": "pmt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "company_id", "currency", "payment_method_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create topup", "tags": [ "Topups" ], "x-group-title": "Payouts" } }, "/transfers": { "get": { "description": "Returns a paginated list of fund transfers, filtered by origin or destination account, with optional sorting and date filtering.\n\nRequired permissions:\n - `payout:transfer:read`", "operationId": "listTransfer", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "origin_id", "required": false, "schema": { "description": "Filter to transfers sent from this account. Accepts a user, company, or ledger account ID.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "destination_id", "required": false, "schema": { "description": "Filter to transfers received by this account. Accepts a user, company, or ledger account ID.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "description": "The column to sort transfers by. Defaults to creation date.", "oneOf": [ { "$ref": "#/components/schemas/CreditTransactionTransfersSortableColumns" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return transfers created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return transfers created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CreditTransactionTransfer.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/TransferListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "List transfers", "tags": [ "Transfers" ], "x-group-title": "Payouts" }, "post": { "description": "Transfer funds between two ledger accounts, such as from a company balance to a user balance.\n\nRequired permissions:\n - `payout:transfer_funds`", "operationId": "createTransfer", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for TransferFunds", "properties": { "amount": { "description": "The amount to transfer in the specified currency. For example, 25.00 for $25.00 USD.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the transfer amount, such as 'usd'." }, "destination_id": { "description": "The identifier of the account receiving the funds. Accepts a user ID ('user_xxx'), company ID ('biz_xxx'), ledger account ID ('ldgr_xxx'), or an email address — emails without an existing Whop user trigger a placeholder-user signup.", "type": "string" }, "idempotence_key": { "description": "A unique key to prevent duplicate transfers. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "A JSON object of custom metadata to attach to the transfer for tracking purposes.", "type": [ "object", "null" ] }, "notes": { "description": "A short note describing the transfer, up to 50 characters.", "type": [ "string", "null" ] }, "origin_id": { "description": "The identifier of the account sending the funds. Accepts a user ID ('user_xxx'), company ID ('biz_xxx'), or ledger account ID ('ldgr_xxx').", "type": "string" } }, "required": [ "amount", "currency", "destination_id", "origin_id" ], "title": "TransferFundsInputWithOriginId", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:transfer_funds" ] } ], "summary": "Create transfer", "tags": [ "Transfers" ], "x-group-title": "Payouts" } }, "/transfers/{id}": { "get": { "description": "Retrieves the details of an existing transfer.\n\nRequired permissions:\n - `payout:transfer:read`", "operationId": "retrieveTransfer", "parameters": [ { "description": "The unique identifier of the transfer to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "ctt_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "Retrieve transfer", "tags": [ "Transfers" ], "x-group-title": "Payouts" } }, "/users": { "get": { "description": "Search for users by name or username, ranked by social proximity to the authenticated user. Returns the user's most recently followed users when no query is given.", "operationId": "listUsers", "parameters": [ { "description": "A search term to filter users by name or username.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The number of users to return (max 50).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns users after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of users to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns users before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/User" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean" }, "has_previous_page": { "type": "boolean" }, "start_cursor": { "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "users listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "List Users", "tags": [ "Users" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/users/me": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates the authenticated user's global profile, or their profile override for an account when account_id is given. Not available to API keys.", "operationId": "updateCurrentUser", "parameters": [ { "description": "When set, updates the authenticated user's profile override for this account instead of their global profile.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bio": { "type": "string" }, "name": { "type": "string" }, "profile_picture": { "properties": { "direct_upload_id": { "type": "string" }, "id": { "type": "string" } }, "type": "object" }, "username": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "current user updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "API keys cannot update a global profile" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Update Current User", "tags": [ "Users" ] } }, "/users/{id}": { "get": { "description": "Retrieves a user's public profile by user_ tag, username, or 'me'.", "operationId": "retrieveUser", "parameters": [ { "description": "When set, returns the user's account-specific profile overrides for this account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "user retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no user with that id" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve User", "tags": [ "Users" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the user, which will look like user_*************, a username, or 'me'.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a user. A user token updates their own global profile; an API key updates the user's account-specific profile override (account_id required).", "operationId": "updateUser", "parameters": [ { "description": "The account whose profile override to update. Required for API key callers.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bio": { "type": "string" }, "name": { "type": "string" }, "profile_picture": { "properties": { "direct_upload_id": { "type": "string" }, "id": { "type": "string" } }, "type": "object" }, "username": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "user updated" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Update User", "tags": [ "Users" ] } }, "/users/{id}/access/{resource_id}": { "get": { "description": "Checks whether a user has access to a company, product, or experience the caller can reach.", "operationId": "checkUserAccess", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_level": { "enum": [ "no_access", "admin", "customer" ], "type": "string" }, "has_access": { "type": "boolean" } }, "required": [ "has_access", "access_level" ], "type": "object" } } }, "description": "access checked" } }, "security": [ { "bearerAuth": [] } ], "summary": "Check User Access", "tags": [ "Users" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The user_ tag or username to check access for.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "A company (biz_), product (prod_), or experience (exp_) ID.", "in": "path", "name": "resource_id", "required": true, "schema": { "type": "string" } } ] }, "/verifications": { "get": { "description": "Returns a list of identity verifications for a payout account, ordered by most recent first.\n\nRequired permissions:\n - `payout:account:read`", "operationId": "listVerification", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "payout_account_id", "required": true, "schema": { "description": "The unique identifier of the payout account to list verifications for.", "example": "poact_xxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Verification.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/VerificationListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List verifications", "tags": [ "Verifications" ], "x-group-title": "Payouts" } }, "/verifications/{id}": { "get": { "description": "Retrieves the details of an existing verification.\n\nRequired permissions:\n - `payout:account:read`", "operationId": "retrieveVerification", "parameters": [ { "description": "The unique identifier of the verification to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "verf_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve verification", "tags": [ "Verifications" ], "x-group-title": "Payouts" } }, "/wallets": { "get": { "description": "Lists every crypto wallet linked to the authenticated resource.", "operationId": "listWallets", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "wallets": { "items": { "properties": { "address": { "type": "string" }, "balance_usd": { "type": "string" }, "network": { "type": "string" } }, "required": [ "address", "network", "balance_usd" ], "type": "object" }, "type": "array" } }, "required": [ "wallets" ], "type": "object" } } }, "description": "wallets listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "wallet lookup failed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Wallets", "tags": [ "Balances" ] } }, "/wallets/balance": { "get": { "description": "Returns per-token balances held in an account's wallet.", "operationId": "retrieveWalletBalance", "parameters": [ { "description": "The business or user account ID whose wallet balance should be returned.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "object": { "enum": [ "balance" ], "type": "string" }, "tokens": { "items": { "properties": { "balance": { "type": "string" }, "icon_url": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "price_usd": { "type": "number" }, "symbol": { "type": "string" }, "token_address": { "nullable": true, "type": "string" }, "value_usd": { "type": "string" } }, "required": [ "symbol", "name", "balance", "value_usd", "price_usd", "icon_url", "token_address" ], "type": "object" }, "type": "array" }, "total_usd": { "type": "string" } }, "required": [ "object", "total_usd", "tokens" ], "type": "object" } } }, "description": "wallet balance retrieved" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account ID is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Retrieve Wallet Balance", "tags": [ "Balances" ] } }, "/wallets/send": { "post": { "description": "Sends USDT from an account's wallet to another Whop user or business.", "operationId": "createWalletSend", "parameters": [ { "description": "The sending account ID.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "USDT amount to send.", "type": "string" }, "to": { "description": "Recipient user ID, business account ID, ledger account ID, or email.", "type": "string" } }, "required": [ "to", "amount" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "destination": { "properties": { "account_id": { "type": "string" }, "address": { "type": "string" } }, "required": [ "account_id", "address" ], "type": "object" }, "object": { "enum": [ "send" ], "type": "string" }, "source": { "properties": { "account_id": { "type": "string" }, "address": { "type": "string" } }, "required": [ "account_id", "address" ], "type": "object" }, "tx_hash": { "type": "string" } }, "required": [ "object", "tx_hash", "amount", "currency", "source", "destination" ], "type": "object" } } }, "description": "wallet send created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the withdraw-funds scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Create Send", "tags": [ "Sends" ] } }, "/webhooks": { "get": { "description": "Returns a paginated list of webhook endpoints configured for a company, ordered by most recently created.\n\nRequired permissions:\n - `developer:manage_webhook`", "operationId": "listWebhook", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list webhooks for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Webhook.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/WebhookListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "List webhooks", "tags": [ "Webhooks" ], "x-group-title": "Developer" }, "post": { "description": "Creates a new webhook\n\nRequired permissions:\n - `developer:manage_webhook`", "operationId": "createWebhook", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateWebhook", "properties": { "api_version": { "description": "The API version for this webhook", "oneOf": [ { "$ref": "#/components/schemas/ApiVersion" }, { "type": "null" } ] }, "child_resource_events": { "description": "Whether or not to send events for child resources. For example, if the webhook is created for a Company, enabling this will only send events from the Company's sub-merchants (child companies).", "type": [ "boolean", "null" ] }, "enabled": { "description": "Whether or not the webhook is enabled.", "type": [ "boolean", "null" ] }, "events": { "description": "The events to send the webhook for.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": [ "array", "null" ] }, "resource_id": { "description": "The resource to create the webhook for. By default this will use current company", "type": [ "string", "null" ] }, "url": { "description": "The URL to send the webhook to.", "example": "https://example.com/path", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A webhook endpoint that receives event notifications for a company via HTTP POST.", "properties": { "api_version": { "$ref": "#/components/schemas/ApiVersion", "description": "The API version used to format payloads sent to this webhook endpoint." }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on a company, enabling this sends events only from the company's sub-merchants (child companies).", "type": "boolean" }, "created_at": { "description": "The datetime the webhook was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "type": "boolean" }, "events": { "description": "The list of event types this webhook is subscribed to.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "id": { "description": "The unique identifier for the webhook.", "example": "hook_xxxxxxxxxxxxx", "type": "string" }, "resource_id": { "description": "The ID of the resource (company or product) this webhook is attached to.", "type": "string" }, "testable_events": { "description": "The subset of subscribed event types that support sending test payloads.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "url": { "description": "The destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/path", "type": "string" }, "webhook_secret": { "description": "The secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic.", "example": "whsec_abc123def456", "type": "string" } }, "required": [ "id", "url", "enabled", "events", "api_version", "created_at", "child_resource_events", "testable_events", "resource_id", "webhook_secret" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Create webhook", "tags": [ "Webhooks" ], "x-group-title": "Developer" } }, "/webhooks/{id}": { "delete": { "description": "Deletes a webhook\n\nRequired permissions:\n - `developer:manage_webhook`", "operationId": "deleteWebhook", "parameters": [ { "description": "The ID of the webhook to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "hook_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Delete webhook", "tags": [ "Webhooks" ], "x-group-title": "Developer" }, "get": { "description": "Retrieves the details of an existing webhook.\n\nRequired permissions:\n - `developer:manage_webhook`", "operationId": "retrieveWebhook", "parameters": [ { "description": "The unique identifier of the webhook to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "hook_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Retrieve webhook", "tags": [ "Webhooks" ], "x-group-title": "Developer" }, "patch": { "description": "Updates a webhook\n\nRequired permissions:\n - `developer:manage_webhook`", "operationId": "updateWebhook", "parameters": [ { "description": "The ID of the Webhook to update", "in": "path", "name": "id", "required": true, "schema": { "example": "hook_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateWebhook", "properties": { "api_version": { "description": "The API version for this webhook", "oneOf": [ { "$ref": "#/components/schemas/ApiVersion" }, { "type": "null" } ] }, "child_resource_events": { "description": "Whether or not to send events for child resources.", "type": [ "boolean", "null" ] }, "enabled": { "description": "Whether or not the webhook is enabled.", "type": [ "boolean", "null" ] }, "events": { "description": "The events to send the webhook for.", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": [ "array", "null" ] }, "url": { "description": "The URL to send the webhook to.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Update webhook", "tags": [ "Webhooks" ], "x-group-title": "Developer" } }, "/withdrawals": { "get": { "description": "Returns a paginated list of withdrawals for a company, with optional sorting and date filtering.\n\nRequired permissions:\n - `payout:withdrawal:read`", "operationId": "listWithdrawal", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": [ "integer", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": true, "schema": { "description": "The unique identifier of the company to list withdrawals for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "description": "The sort direction for results. Defaults to descending.", "oneOf": [ { "$ref": "#/components/schemas/Direction" }, { "type": "null" } ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return withdrawals created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return withdrawals created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicWithdrawal.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/WithdrawalListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:withdrawal:read" ] } ], "summary": "List withdrawals", "tags": [ "Withdrawals" ], "x-group-title": "Payouts" }, "post": { "description": "Creates a withdrawal request for a ledger account\n\nRequired permissions:\n - `payout:withdraw_funds`\n - `payout:destination:read`", "operationId": "createWithdrawal", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateLedgerWithdrawal", "properties": { "amount": { "description": "The amount to withdraw in the specified currency", "example": 6.9, "type": "number" }, "company_id": { "description": "The ID of the company to withdraw from.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency that is being withdrawn." }, "payout_method_id": { "description": "The ID of the payout method to use for the withdrawal.", "type": [ "string", "null" ] }, "platform_covers_fees": { "description": "Whether the platform covers the payout fees instead of the connected account.", "type": [ "boolean", "null" ] }, "statement_descriptor": { "description": "Custom statement descriptor for the withdrawal. Must be between 5 and 22 characters and contain only alphanumeric characters.", "type": [ "string", "null" ] } }, "required": [ "amount", "company_id", "currency" ], "title": "CreateLedgerWithdrawalInputAndCompanyId", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds", "payout:destination:read" ] } ], "summary": "Create withdrawal", "tags": [ "Withdrawals" ], "x-group-title": "Payouts" } }, "/withdrawals/{id}": { "get": { "description": "Retrieves the details of an existing withdrawal.\n\nRequired permissions:\n - `payout:withdrawal:read`\n - `payout:destination:read`", "operationId": "retrieveWithdrawal", "parameters": [ { "description": "The unique identifier of the withdrawal to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "wdrl_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:withdrawal:read", "payout:destination:read" ] } ], "summary": "Retrieve withdrawal", "tags": [ "Withdrawals" ], "x-group-title": "Payouts" } } }, "servers": [ { "description": "Production Whop API", "url": "https://api.whop.com/api/v1" }, { "description": "Sandbox Whop API", "url": "https://sandbox-api.whop.com/api/v1" } ], "tags": [ { "description": "Products", "name": "Products" }, { "description": "Payments", "name": "Payments" }, { "description": "Refunds", "name": "Refunds" }, { "description": "Disputes", "name": "Disputes" }, { "description": "Dispute alerts", "name": "Dispute alerts" }, { "description": "Resolution center cases", "name": "Resolution center cases" }, { "description": "Checkout configurations", "name": "Checkout configurations" }, { "description": "Setup intents", "name": "Setup intents" }, { "description": "Payment methods", "name": "Payment methods" }, { "description": "Invoices", "name": "Invoices" }, { "description": "Promo codes", "name": "Promo codes" }, { "description": "Card transactions", "name": "Card transactions" }, { "description": "Ledger accounts", "name": "Ledger accounts" }, { "description": "Transfers", "name": "Transfers" }, { "description": "Withdrawals", "name": "Withdrawals" }, { "description": "Payout methods", "name": "Payout methods" }, { "description": "Verifications", "name": "Verifications" }, { "description": "Identity profiles", "name": "Identity profiles" }, { "description": "Payout accounts", "name": "Payout accounts" }, { "description": "Topups", "name": "Topups" }, { "description": "Companies", "name": "Companies" }, { "description": "Authorized users", "name": "Authorized users" }, { "description": "Fee markups", "name": "Fee markups" }, { "description": "Members", "name": "Members" }, { "description": "Memberships", "name": "Memberships" }, { "description": "Leads", "name": "Leads" }, { "description": "Entries", "name": "Entries" }, { "description": "Shipments", "name": "Shipments" }, { "description": "Reviews", "name": "Reviews" }, { "description": "Company token transactions", "name": "Company token transactions" }, { "description": "Affiliates", "name": "Affiliates" }, { "description": "Experiences", "name": "Experiences" }, { "description": "Forums", "name": "Forums" }, { "description": "Forum posts", "name": "Forum posts" }, { "description": "Chat channels", "name": "Chat channels" }, { "description": "Support channels", "name": "Support channels" }, { "description": "Messages", "name": "Messages" }, { "description": "Reactions", "name": "Reactions" }, { "description": "Dm members", "name": "Dm members" }, { "description": "Dm channels", "name": "Dm channels" }, { "description": "Notifications", "name": "Notifications" }, { "description": "Courses", "name": "Courses" }, { "description": "Course chapters", "name": "Course chapters" }, { "description": "Course lessons", "name": "Course lessons" }, { "description": "Course students", "name": "Course students" }, { "description": "Course lesson interactions", "name": "Course lesson interactions" }, { "description": "Apps", "name": "Apps" }, { "description": "Webhooks", "name": "Webhooks" }, { "description": "App builds", "name": "App builds" }, { "description": "Access tokens", "name": "Access tokens" }, { "description": "Account links", "name": "Account links" }, { "description": "Files", "name": "Files" }, { "description": "Ai chats", "name": "Ai chats" }, { "description": "Bounties", "name": "Bounties" }, { "description": "Stats", "name": "Stats" }, { "description": "Ad campaigns", "name": "Ad campaigns" }, { "description": "Ad groups", "name": "Ad groups" }, { "description": "Ads", "name": "Ads" }, { "description": "Conversions", "name": "Conversions" }, { "description": "Ad reports", "name": "Ad reports" } ], "webhooks": { "course_lesson_interaction.completed": { "post": { "description": "Sent when a course lesson interaction is completed\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`\n - `webhook_receive:courses`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CourseLessonInteraction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "course_lesson_interaction.completed", "description": "The webhook event type", "example": "course_lesson_interaction.completed", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CourseLessonInteraction Completed", "tags": [ "Course lesson interactions" ] } }, "dispute.created": { "post": { "description": "Sent when a dispute is created\n\nRequired permissions:\n - `payment:dispute:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:disputes`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Dispute" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "dispute.created", "description": "The webhook event type", "example": "dispute.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Dispute Created", "tags": [ "Disputes" ] } }, "dispute.updated": { "post": { "description": "Sent when a dispute is updated\n\nRequired permissions:\n - `payment:dispute:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:disputes`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Dispute" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "dispute.updated", "description": "The webhook event type", "example": "dispute.updated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Dispute Updated", "tags": [ "Disputes" ] } }, "dispute_alert.created": { "post": { "description": "Sent when a dispute alert is created\n\nRequired permissions:\n - `payment:dispute_alert:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `payment:dispute:read`\n - `webhook_receive:disputes`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/DisputeAlert" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "dispute_alert.created", "description": "The webhook event type", "example": "dispute_alert.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "DisputeAlert Created", "tags": [ "Dispute alerts" ] } }, "entry.approved": { "post": { "description": "Sent when a entry is approved\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.approved", "description": "The webhook event type", "example": "entry.approved", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Approved", "tags": [ "Entries" ] } }, "entry.created": { "post": { "description": "Sent when a entry is created\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.created", "description": "The webhook event type", "example": "entry.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Created", "tags": [ "Entries" ] } }, "entry.deleted": { "post": { "description": "Sent when a entry is deleted\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.deleted", "description": "The webhook event type", "example": "entry.deleted", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Deleted", "tags": [ "Entries" ] } }, "entry.denied": { "post": { "description": "Sent when a entry is denied\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.denied", "description": "The webhook event type", "example": "entry.denied", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Denied", "tags": [ "Entries" ] } }, "identity_profile.approved": { "post": { "description": "Sent when a identity profile is approved\n\nRequired permissions:\n - `identity:read`\n - `webhook_receive:identity_profiles`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/IdentityProfile" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "identity_profile.approved", "description": "The webhook event type", "example": "identity_profile.approved", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "IdentityProfile Approved", "tags": [ "Identity profiles" ] } }, "identity_profile.needs_action": { "post": { "description": "Sent when a identity profile is needs action\n\nRequired permissions:\n - `identity:read`\n - `webhook_receive:identity_profiles`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/IdentityProfile" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "identity_profile.needs_action", "description": "The webhook event type", "example": "identity_profile.needs_action", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "IdentityProfile Needs action", "tags": [ "Identity profiles" ] } }, "identity_profile.rejected": { "post": { "description": "Sent when a identity profile is rejected\n\nRequired permissions:\n - `identity:read`\n - `webhook_receive:identity_profiles`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/IdentityProfile" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "identity_profile.rejected", "description": "The webhook event type", "example": "identity_profile.rejected", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "IdentityProfile Rejected", "tags": [ "Identity profiles" ] } }, "identity_profile.updated": { "post": { "description": "Sent when a identity profile is updated\n\nRequired permissions:\n - `identity:read`\n - `webhook_receive:identity_profiles`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/IdentityProfile" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "identity_profile.updated", "description": "The webhook event type", "example": "identity_profile.updated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "IdentityProfile Updated", "tags": [ "Identity profiles" ] } }, "invoice.created": { "post": { "description": "Sent when a invoice is created\n\nRequired permissions:\n - `invoice:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.created", "description": "The webhook event type", "example": "invoice.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Created", "tags": [ "Invoices" ] } }, "invoice.marked_uncollectible": { "post": { "description": "Sent when a invoice is marked uncollectible\n\nRequired permissions:\n - `invoice:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.marked_uncollectible", "description": "The webhook event type", "example": "invoice.marked_uncollectible", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Marked uncollectible", "tags": [ "Invoices" ] } }, "invoice.paid": { "post": { "description": "Sent when a invoice is paid\n\nRequired permissions:\n - `invoice:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.paid", "description": "The webhook event type", "example": "invoice.paid", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Paid", "tags": [ "Invoices" ] } }, "invoice.past_due": { "post": { "description": "Sent when a invoice is past due\n\nRequired permissions:\n - `invoice:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.past_due", "description": "The webhook event type", "example": "invoice.past_due", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Past due", "tags": [ "Invoices" ] } }, "invoice.voided": { "post": { "description": "Sent when a invoice is voided\n\nRequired permissions:\n - `invoice:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.voided", "description": "The webhook event type", "example": "invoice.voided", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Voided", "tags": [ "Invoices" ] } }, "membership.activated": { "post": { "description": "Sent when a membership is activated\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:memberships`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "membership.activated", "description": "The webhook event type", "example": "membership.activated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Activated", "tags": [ "Memberships" ] } }, "membership.cancel_at_period_end_changed": { "post": { "description": "Sent when a membership is cancel at period end changed\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:memberships`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "membership.cancel_at_period_end_changed", "description": "The webhook event type", "example": "membership.cancel_at_period_end_changed", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Cancel at period end changed", "tags": [ "Memberships" ] } }, "membership.deactivated": { "post": { "description": "Sent when a membership is deactivated\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:memberships`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "membership.deactivated", "description": "The webhook event type", "example": "membership.deactivated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Deactivated", "tags": [ "Memberships" ] } }, "payment.created": { "post": { "description": "Sent when a payment is created\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.created", "description": "The webhook event type", "example": "payment.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Created", "tags": [ "Payments" ] } }, "payment.failed": { "post": { "description": "Sent when a payment is failed\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.failed", "description": "The webhook event type", "example": "payment.failed", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Failed", "tags": [ "Payments" ] } }, "payment.pending": { "post": { "description": "Sent when a payment is pending\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.pending", "description": "The webhook event type", "example": "payment.pending", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Pending", "tags": [ "Payments" ] } }, "payment.succeeded": { "post": { "description": "Sent when a payment is succeeded\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.succeeded", "description": "The webhook event type", "example": "payment.succeeded", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Succeeded", "tags": [ "Payments" ] } }, "payout_account.status_updated": { "post": { "description": "Sent when a payout account is status updated\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:payout_accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/PayoutAccount" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout_account.status_updated", "description": "The webhook event type", "example": "payout_account.status_updated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "PayoutAccount Status updated", "tags": [ "Payout accounts" ] } }, "payout_method.created": { "post": { "description": "Sent when a payout method is created\n\nRequired permissions:\n - `payout:destination:read`\n - `webhook_receive:payout_methods`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/PayoutMethod" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout_method.created", "description": "The webhook event type", "example": "payout_method.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "PayoutMethod Created", "tags": [ "Payout methods" ] } }, "refund.created": { "post": { "description": "Sent when a refund is created\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:refunds`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Refund" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "refund.created", "description": "The webhook event type", "example": "refund.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Refund Created", "tags": [ "Refunds" ] } }, "refund.updated": { "post": { "description": "Sent when a refund is updated\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:refunds`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Refund" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "refund.updated", "description": "The webhook event type", "example": "refund.updated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Refund Updated", "tags": [ "Refunds" ] } }, "resolution_center_case.created": { "post": { "description": "Sent when a resolution center case is created\n\nRequired permissions:\n - `payment:resolution_center_case:read`\n - `webhook_receive:resolutions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "resolution_center_case.created", "description": "The webhook event type", "example": "resolution_center_case.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "ResolutionCenterCase Created", "tags": [ "Resolution center cases" ] } }, "resolution_center_case.decided": { "post": { "description": "Sent when a resolution center case is decided\n\nRequired permissions:\n - `payment:resolution_center_case:read`\n - `webhook_receive:resolutions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "resolution_center_case.decided", "description": "The webhook event type", "example": "resolution_center_case.decided", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "ResolutionCenterCase Decided", "tags": [ "Resolution center cases" ] } }, "resolution_center_case.updated": { "post": { "description": "Sent when a resolution center case is updated\n\nRequired permissions:\n - `payment:resolution_center_case:read`\n - `webhook_receive:resolutions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "resolution_center_case.updated", "description": "The webhook event type", "example": "resolution_center_case.updated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "ResolutionCenterCase Updated", "tags": [ "Resolution center cases" ] } }, "setup_intent.canceled": { "post": { "description": "Sent when a setup intent is canceled\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:setup_intents`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "setup_intent.canceled", "description": "The webhook event type", "example": "setup_intent.canceled", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "SetupIntent Canceled", "tags": [ "Setup intents" ] } }, "setup_intent.requires_action": { "post": { "description": "Sent when a setup intent is requires action\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:setup_intents`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "setup_intent.requires_action", "description": "The webhook event type", "example": "setup_intent.requires_action", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "SetupIntent Requires action", "tags": [ "Setup intents" ] } }, "setup_intent.succeeded": { "post": { "description": "Sent when a setup intent is succeeded\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:setup_intents`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "setup_intent.succeeded", "description": "The webhook event type", "example": "setup_intent.succeeded", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "SetupIntent Succeeded", "tags": [ "Setup intents" ] } }, "verification.succeeded": { "post": { "description": "Sent when a verification is succeeded\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:verifications`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Verification" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "verification.succeeded", "description": "The webhook event type", "example": "verification.succeeded", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Verification Succeeded", "tags": [ "Verifications" ] } }, "withdrawal.created": { "post": { "description": "Sent when a withdrawal is created\n\nRequired permissions:\n - `payout:withdrawal:read`\n - `payout:destination:read`\n - `webhook_receive:withdrawals`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Withdrawal" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "withdrawal.created", "description": "The webhook event type", "example": "withdrawal.created", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Withdrawal Created", "tags": [ "Withdrawals" ] } }, "withdrawal.updated": { "post": { "description": "Sent when a withdrawal is updated\n\nRequired permissions:\n - `payout:withdrawal:read`\n - `payout:destination:read`\n - `webhook_receive:withdrawals`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "company_id": { "description": "The company ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Withdrawal" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "withdrawal.updated", "description": "The webhook event type", "example": "withdrawal.updated", "type": "string" } }, "required": [ "id", "api_version", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Withdrawal Updated", "tags": [ "Withdrawals" ] } } } }