{ "components": { "parameters": { "ApiVersionDate": { "description": "Pins the request to a dated API version.", "in": "header", "name": "Api-Version-Date", "required": false, "schema": { "example": "2026-08-25-2", "type": "string" } }, "IdempotencyKey": { "description": "A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency).", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "example": "d9105228-4a08-46b1-8b91-42fed586d383", "maxLength": 255, "type": "string" } } }, "responses": { "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Conflict" }, "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" }, "ServiceUnavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Service Unavailable" }, "TooManyRequests": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Too Many Requests" }, "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": { "balances": { "items": { "$ref": "#/components/schemas/AccountBalanceToken", "description": "Account holdings, each with USD value. Empty when `total_usd` is `null`." }, "type": "array" }, "banner_image_url": { "description": "Account banner image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "business_address": { "description": "Account business address used to calculate tax, with `line1`, `line2`, `city`, `state`, `postal_code`, and `country`. `null` when no address is set.", "example": { "city": "Austin", "country": "US", "line1": "4180 Burnet Rd", "line2": "Suite 2", "postal_code": "78756", "state": "TX" }, "type": [ "object", "null" ] }, "business_name": { "description": "The account's legal business name used with its tax address.", "example": "Shine Time Auto Detailing, LLC", "maxLength": 255, "type": [ "string", "null" ] }, "business_type": { "description": "High-level business category for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "education_program", "coaching", "software", "paid_group", "newsletter", "agency", "physical_products", "brick_and_mortar", "events", "coaching_and_courses", "other", "services", "gig_economy", "marketplace", "telehealth", "class_action_settlement", "physical_product", "saas", "course", "community", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "can_transfer_pending_balance_to_children": { "description": "Whether pending funds may be transferred from this platform account to its connected accounts.", "example": false, "type": "boolean" }, "capabilities": { "description": "Payment rails enabled for this account, each `active`, `inactive`, or `pending` (onboarding or review in progress). Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise.", "oneOf": [ { "$ref": "#/components/schemas/AccountCapabilities" }, { "type": "null" } ] }, "cards": { "description": "Whop Cards application details for the account. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise, or when the account has no card application.", "oneOf": [ { "$ref": "#/components/schemas/AccountCards" }, { "type": "null" } ] }, "collect_vat_id": { "description": "Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does not require a VAT ID to purchase.", "example": true, "type": "boolean" }, "company_formation": { "$ref": "#/components/schemas/AccountCompanyFormation", "description": "Company formation state for the account, managed through [Form Company](/api-reference/beta/accounts/form-company). A `draft` `status` until the formation checkout is paid, then filing progress with downloadable documents and signatures awaiting action. Empty when the formation state is temporarily unavailable." }, "country": { "description": "Country where the account is located.", "example": "us", "type": [ "string", "null" ] }, "created_at": { "description": "When the account was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "description": { "description": "Account promotional description.", "example": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "type": [ "string", "null" ] }, "email": { "description": "Account owner email address.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "eula": { "description": "The account's end-user license agreement document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "home_preferences": { "items": { "description": "Public account home page preferences.", "enum": [ "hide_member_count", "hide_members_card" ], "example": "hide_member_count", "type": "string" }, "type": "array" }, "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "industry_group": { "description": "Account industry group. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "academic_and_test_prep", "accessories", "agriculture_and_farming", "ai_and_automation_agencies", "ai_and_automation_software", "arts_and_crafts", "automotive", "b2b_and_professional_marketplaces", "baby_and_kids", "bars_and_breweries", "beauty_and_personal_care", "beauty_and_wellness", "business_and_entrepreneurship", "business_and_money_groups", "cafes_and_quick_service", "career_and_professional", "charity_and_cause_events", "class_action_settlement", "clothing_and_apparel", "communication_and_messaging_software", "community_and_education_software", "conference_and_expo_events", "consulting", "content_and_clipping_agencies", "creative_and_content_creation", "creative_and_content_groups", "creative_and_education", "creative_gigs", "creative_services", "customer_support_agencies", "dating_and_relationships", "delivery_and_logistics", "dental_and_vision", "dermatology_and_skin", "design_and_creative_agencies", "developer_and_technical_tools", "development_agencies", "digital_and_education_marketplaces", "digital_goods_and_accounts", "e_commerce_software", "education_and_childcare", "educational_training_events", "electronics_and_gadgets", "entertainment_and_leisure", "family_and_community_events", "finance_and_investing", "fitness_and_athletics", "fitness_and_health_groups", "fitness_and_recreation", "fitness_equipment_and_gear", "food_and_beverages", "food_and_hospitality_marketplaces", "funeral_and_death_care", "gaming_and_entertainment_software", "gaming_groups", "genetic_and_specialized", "government_and_public", "health_and_wellness", "health_and_wellness_services", "healthcare", "healthcare_and_wellness_software", "hobbies_and_lifestyle", "hobby_and_interest_groups", "home_and_living", "home_and_trade_services", "home_and_trade_storefronts", "home_improvement_and_tools", "home_services_gigs", "hospitality_and_lodging", "industrial_and_manufacturing", "industry_specific_software", "language_and_communication", "legal_and_compliance", "lifestyle_and_culture", "lifestyle_and_personal_growth", "lifestyle_and_personal_growth_groups", "lifestyle_and_wellness_events", "logistics_and_transportation_services", "marketing_agencies", "marketing_and_advertising", "marketing_and_sales_software", "media_and_publishing_companies", "mental_health_and_behavioral", "miscellaneous", "music_and_performing_arts", "news_and_politics", "nonprofit_and_charity", "office_and_business_supplies", "outdoor_and_sports", "performance_and_show_events", "personal_development", "personal_finance", "personal_services", "pet_services", "pets_and_animals", "primary_and_general_care", "product_marketplaces", "productivity_and_business_ops", "professional_gigs", "professional_services", "professional_services_storefront", "publishing_and_info_products", "real_estate", "real_estate_software", "recruiting_and_staffing", "rehabilitation_and_therapy", "religion_and_faith", "rental_marketplaces", "restaurants", "retail", "sales_agencies", "sales_and_revenue", "security_and_investigations", "security_and_privacy_software", "service_marketplaces", "sleep_and_chronic_conditions", "social_and_networking_events", "social_entertainment_events", "specialized_gigs", "specialty_medical_care", "spirituality_and_mindfulness", "spirituality_and_personal_growth", "sports_and_fitness_events", "sports_betting_and_gambling", "sports_betting_groups", "supplements_and_nutrition", "sustainability_and_eco_products", "task_and_errands", "tech_and_ai", "tech_and_dev_groups", "tech_and_development", "trading_and_finance_software", "trading_and_investing", "trading_and_investing_groups", "transportation", "veterinary", "video_games_and_esports", "weight_and_metabolic_health", "wellness_and_alternative", "womens_and_mens_health", null ], "example": "automotive", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "industry_type": { "description": "Specific industry vertical for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "trading", "sports_betting", "reselling", "fitness", "amazon_fba", "real_estate", "kindle_book_publishing", "dating", "agencies", "health_and_wellness", "social_media", "sales", "business", "ecommerce", "video_games", "home_services", "ai", "public_speaking", "personal_finance", "careers", "travel", "clipping", "spirituality", "vas", "personal_development", "software", "other", "marketing_agency", "sales_agency", "ai_agency", "design_agency", "coaching_agency", "development_agency", "recruiting_agency", "customer_support_agency", "clipping_agency", "clothing", "supplements", "beauty_and_personal_care", "fitness_gear", "accessories", "home_goods", "electronics_and_gadgets", "food_and_beverages", "gym", "restaurant", "retail_store", "coffee_shop", "salon_spa", "medical_dentist_office", "hotel_lodging", "auto_repair_shop", "masterminds", "webinars", "bootcamps", "convention", "concerts", "meetups", "parties", "forex_trading", "stock_trading", "options_trading", "crypto_trading", "futures_trading", "day_trading", "swing_trading", "algorithmic_trading", "prop_firm_trading", "value_investing", "real_estate_investing", "alternative_investments", "penny_stock_trading", "dividend_investing", "index_fund_investing", "gold_precious_metals", "venture_capital_education", "private_equity_education", "technical_analysis", "forex_scalping", "ict_smc_trading", "personalized_investment_advice", "forex_signals_group", "stock_signals_group", "crypto_signals_group", "options_alerts_group", "futures_signals_group", "trading_education_group", "investing_community", "prediction_markets_group", "nft_alpha_group", "penny_stock_group", "dividend_investing_group", "real_estate_investing_group", "prop_firm_group", "forex_trading_bot", "stock_trading_platform", "crypto_trading_bot", "futures_trading_bot", "options_flow_tool", "portfolio_tracker", "financial_modeling_software", "accounting_software", "invoicing_software", "tax_software", "risk_management_software", "prop_trading_platform", "backtesting_software", "trading_indicators", "market_data_feed", "stock_research_tool", "banking_software", "lending_platform", "insurance_software", "bnpl_service", "check_cashing_service", "cloud_mining_schemes", "consumer_lending", "credit_repair_service", "crypto_exchange_brokerage", "crypto_trading_tools_software", "debt_collection_agency", "debt_relief_settlement", "escrow_service", "foreign_exchange_service", "non_custodial_wallet_tools", "payment_facilitation", "prediction_market_exchange", "stablecoin_issuance", "token_sales_ico", "tokenized_rwa", "yield_staking_products", "sports_betting_picks", "fantasy_sports", "horse_racing", "poker_coaching", "esports_betting", "sports_analytics", "nfl_betting", "nba_betting", "mlb_betting", "soccer_betting", "mma_ufc_betting", "sports_picks_group", "dfs_group", "horse_racing_group", "esports_picks_group", "nfl_picks_group", "nba_picks_group", "soccer_picks_group", "mlb_picks_group", "mma_picks_group", "prop_bets_group", "fantasy_sports_free_to_play", "licensed_gambling_operations", "unlicensed_gambling", "bodybuilding_coaching", "strength_training", "weight_loss_coaching", "athletic_performance", "yoga_instruction", "martial_arts_instruction", "running_coaching", "calisthenics", "flexibility_mobility", "nutrition_coaching", "swimming_coaching", "cycling_coaching", "boxing_coaching", "mma_coaching", "jiu_jitsu_coaching", "wrestling_coaching", "gymnastics_coaching", "pilates_instruction", "sports_nutrition", "body_recomposition", "golf_coaching", "tennis_coaching", "basketball_training", "soccer_training", "racket_sports_coaching", "fitness_accountability", "nutrition_community", "weight_loss_group", "bodybuilding_community", "running_community", "martial_arts_community", "mental_health_group", "biohacking_community", "addiction_support_group", "yoga_community", "crossfit_community", "longevity_community", "womens_fitness_community", "postpartum_fitness_group", "chronic_illness_support", "skincare_community", "mental_health_coaching", "life_coaching", "biohacking", "holistic_health", "addiction_recovery_coaching", "breathwork", "meditation_mindfulness", "gut_health_coaching", "longevity_coaching", "womens_health_coaching", "mens_health_coaching", "fertility_wellness", "stress_management", "grief_coaching", "trauma_recovery_coaching", "adhd_coaching", "biomarker_health_coaching", "telehealth_platform", "ehr_software", "practice_management", "mental_health_app", "fitness_app", "nutrition_tracking_app", "wellness_app", "patient_engagement", "medical_billing_software", "pharmacy_management", "lab_management", "clinical_trial_software", "dental_software", "veterinary_software", "health_data_platform", "fitness_newsletter", "mental_health_newsletter", "longevity_newsletter", "medical_newsletter", "biohacking_newsletter", "womens_health_newsletter", "mens_health_newsletter", "pharma_biotech_newsletter", "ecommerce_education", "amazon_fba_coaching", "dropshipping_coaching", "print_on_demand_coaching", "retail_arbitrage", "wholesale_coaching", "startup_coaching", "business_strategy", "agency_building", "smma_coaching", "consulting_business", "saas_entrepreneurship", "local_business_coaching", "cleaning_business_coaching", "trucking_business_coaching", "vending_machine_business", "atm_business_coaching", "car_wash_business", "airbnb_business_coaching", "private_label_coaching", "etsy_coaching", "merch_business_coaching", "licensing_business", "business_acquisition", "women_entrepreneurship", "affiliate_marketing_education", "coaching_business_coaching", "ecommerce_community", "agency_community", "saas_community", "saas_marketing_community", "real_estate_community", "sales_community", "affiliate_community", "reselling_community", "amazon_seller_community", "dropshipping_community", "freelancer_community", "startup_founder_community", "ceo_executive_community", "women_business_community", "marketing_community", "ai_business_community", "content_business_community", "local_business_community", "private_equity_community", "wholesaling_community", "coaching_business_community", "make_money_online_community", "startup_newsletter", "ecommerce_newsletter", "marketing_newsletter", "sales_newsletter", "small_business_newsletter", "leadership_newsletter", "agency_newsletter", "saas_newsletter", "hr_people_newsletter", "legal_business_newsletter", "real_estate_business_newsletter", "solopreneur_newsletter", "high_ticket_sales", "b2b_sales_coaching", "door_to_door_sales", "sales_funnel_coaching", "appointment_setting_coaching", "insurance_sales_coaching", "car_sales_coaching", "retail_sales_coaching", "solar_sales_coaching", "lead_generation_agency", "cold_email_agency", "cold_calling_agency", "sales_outsourcing", "crm_implementation", "appointment_setting_agency", "sales_training_agency", "revenue_operations_agency", "inbound_teleservices", "outbound_telemarketing", "facebook_ads", "google_ads", "tiktok_marketing", "youtube_marketing", "instagram_growth", "seo_coaching", "email_marketing_coaching", "copywriting_coaching", "affiliate_marketing", "local_seo", "ai_marketing", "webinar_marketing", "event_marketing", "saas_marketing_coaching", "digital_marketing", "smma", "performance_marketing_agency", "seo_agency", "content_marketing_agency", "email_marketing_agency", "influencer_marketing_agency", "pr_agency", "branding_agency", "video_marketing_agency", "amazon_marketing_agency", "podcast_marketing_agency", "tiktok_agency", "linkedin_agency", "local_marketing_agency", "dental_marketing_agency", "real_estate_marketing_agency", "restaurant_marketing_agency", "ecommerce_marketing_agency", "b2b_marketing_agency", "growth_marketing_agency", "affiliate_management_agency", "conversion_optimization_agency", "event_marketing_agency", "click_farm_service", "data_scraping_service", "lead_list_sales", "social_media_bot_farm", "crm_software", "email_marketing_software", "sms_marketing_software", "seo_tool", "landing_page_builder", "ad_management_tool", "affiliate_tracking", "review_management", "analytics_dashboard", "lead_gen_software", "link_in_bio_tool", "influencer_platform", "webinar_platform", "ab_testing_tool", "chatbot_marketing", "video_sales_tool", "proposal_software", "competitive_intelligence", "social_listening_tool", "whatsapp_marketing_tool", "standalone_tipping", "video_editing_education", "photography_coaching", "music_production", "ui_ux_design_education", "clipping_education", "ugc_creation", "3d_modeling_education", "dj_education", "youtube_automation", "blog_monetization", "wedding_photography_education", "calligraphy_lettering", "illustration_education", "fashion_design_education", "interior_design_education", "influencer_education", "ai_content_creator_education", "ai_nsfw_content_generation_education", "web_design_agency", "graphic_design_agency", "ui_ux_agency", "motion_design_agency", "product_design_agency", "logo_design_agency", "presentation_design_agency", "3d_visualization_agency", "fashion_design_agency", "video_clipping_agency", "video_production_agency", "ugc_agency", "content_writing_agency", "translation_agency", "social_media_management", "ghostwriting_agency", "podcast_editing_agency", "thumbnail_design_agency", "scriptwriting_agency", "seo_content_agency", "technical_writing_agency", "photography_service", "videography_service", "music_production_service", "voice_over_service", "event_photography", "drone_services", "commercial_photography", "portrait_photography_service", "real_estate_photography", "food_photography_service", "live_event_production", "podcast_production_service", "freelance_design_gig", "freelance_writing_gig", "freelance_dev_gig", "music_performance_gig", "event_staffing_gig", "model_talent_gig", "photography_gig", "videography_gig", "voiceover_gig", "illustration_gig", "social_media_gig", "dj_gig", "face_painting_gig", "clipping_gig", "content_creator_community", "video_editing_community", "music_producer_community", "photography_community", "writing_community", "design_community", "youtube_creator_community", "tiktok_creator_community", "podcast_community", "filmmaker_community", "clipping_community", "youtube_automation_community", "pirated_digital_content", "web_development_education", "ai_ml_education", "data_science_education", "cybersecurity_education", "cloud_computing_education", "blockchain_education", "no_code_education", "automation_education", "game_development_education", "prompt_engineering", "python_programming", "javascript_programming", "react_development", "database_engineering", "aws_certification", "data_engineering", "robotics_education", "vr_ar_development", "linux_sysadmin", "wordpress_development", "ai_agent_building", "web_development_agency", "mobile_app_agency", "saas_development_agency", "ecommerce_development", "blockchain_development_agency", "game_development_agency", "devops_agency", "ai_development_agency", "wordpress_agency", "shopify_agency", "api_integration_agency", "cybersecurity_agency", "data_engineering_agency", "vr_ar_development_agency", "hacking_tools_malware", "stalkerware_monitoring", "developer_community", "ai_community", "cybersecurity_community", "no_code_community", "indie_hacker_community", "devops_community", "data_science_community", "product_community", "open_source_community", "api_management", "hosting_platform", "database_tool", "devops_tool", "monitoring_tool", "testing_tool", "code_editor", "no_code_builder", "cdn_platform", "error_tracking", "documentation_tool", "webhook_tool", "3d_weapon_files", "background_check_services", "document_falsification", "fake_id_services", "fake_reference_services", "real_estate_wholesaling", "house_flipping", "property_development", "rental_property", "airbnb_str", "commercial_real_estate", "land_investing", "section_8_housing", "mobile_home_investing", "multifamily_investing", "self_storage_investing", "property_management_education", "vacation_rental_management", "real_estate_crm", "property_management_software", "deal_analysis_tool", "mls_search_tool", "virtual_tour_software", "real_estate_marketing_software", "construction_management", "home_valuation_tool", "credit_repair_education", "budgeting_coaching", "tax_strategy_education", "wealth_building", "student_loan_strategy", "credit_card_optimization", "career_coaching", "executive_coaching", "management_coaching", "tech_career_coaching", "medical_career_coaching", "trade_skills_education", "va_training", "bookkeeping_education", "data_career_coaching", "cybersecurity_career", "consulting_career", "investment_banking_career", "law_career_coaching", "nursing_career_coaching", "teaching_career_coaching", "personal_branding_career", "mens_dating_coaching", "womens_dating_coaching", "relationship_coaching", "marriage_coaching", "communication_coaching", "masculinity_coaching", "femininity_coaching", "breakup_recovery", "manifestation_coaching", "astrology_coaching", "energy_healing", "spiritual_coaching", "faith_based_coaching", "psychic_development", "numerology_coaching", "chakra_healing", "shamanic_healing", "biblical_coaching", "islamic_coaching", "productivity_coaching", "public_speaking_coaching", "mindset_coaching", "stoicism_philosophy", "mens_self_improvement", "womens_self_improvement", "leadership_development", "anger_management", "neurolinguistic_programming", "appearance_and_grooming_coaching", "amazon_kdp", "self_publishing", "audiobook_publishing", "course_creation", "digital_product_creation", "ghostwriting_business", "template_creation", "ai_book_publishing", "language_learning", "tutoring", "college_admissions_coaching", "cpa_exam_prep", "bar_exam_prep", "real_estate_exam_prep", "medical_board_prep", "pmp_certification_prep", "aws_certification_prep", "comptia_certification", "ap_exam_prep", "graduate_school_prep", "scholarship_coaching", "homeschool_education", "stem_education", "financial_certification", "coding_bootcamp_prep", "cooking_culinary", "travel_coaching", "parenting_coaching", "pet_training", "gardening_education", "diy_crafts", "survival_prepping", "baking_pastry", "wine_sommelier", "beer_brewing", "mixology_bartending", "woodworking", "pottery_ceramics", "knitting_crocheting", "jewelry_making", "aquarium_fishkeeping", "bird_watching", "astronomy_education", "magic_illusion", "car_restoration", "motorcycle_riding", "sailing_boating", "scuba_diving", "rock_climbing", "skiing_snowboarding", "surfing_education", "homesteading", "tiny_house_living", "van_life", "fashion_styling", "floral_design", "travel_planning_service", "collectibles_coaching", "car_enthusiast_community", "sneakerhead_community", "watch_collector_community", "wine_enthusiast_community", "cigar_community", "cooking_community", "gardening_community", "fishing_community", "hunting_community", "diy_maker_community", "golf_community", "collectibles_community", "sweepstakes_raffles", "event_ticket_community", "esports_coaching", "game_specific_coaching", "gaming_community", "game_account_selling", "unauthorized_ingame_currency", "legal_education", "music_theory", "music_business", "acting_coaching", "dance_instruction", "voice_acting", "english_coaching", "spanish_coaching", "mandarin_coaching", "french_coaching", "german_coaching", "japanese_coaching", "korean_coaching", "arabic_coaching", "sign_language_education", "accent_reduction", "business_english", "ai_chatbot_agency", "ai_automation_agency", "ai_consulting", "workflow_automation_agency", "data_analytics_agency", "ai_voice_agent_agency", "ai_content_agency", "machine_learning_agency", "computer_vision_agency", "tech_recruiting_agency", "executive_recruiting", "staffing_agency", "remote_staffing", "healthcare_recruiting", "va_placement_agency", "sales_recruiting", "creative_recruiting", "finance_recruiting", "legal_recruiting", "construction_staffing", "hospitality_staffing", "customer_support_outsourcing", "live_chat_agency", "technical_support_agency", "call_center_agency", "multilingual_support_agency", "community_management_agency", "management_consulting", "financial_consulting", "hr_consulting", "operations_consulting", "it_consulting", "sustainability_consulting", "legal_consulting", "compliance_consulting", "supply_chain_consulting", "change_management_consulting", "digital_transformation_consulting", "healthcare_consulting", "real_estate_consulting", "franchise_consulting", "export_trade_consulting", "nonprofit_consulting", "education_consulting", "cannabis_consulting", "restaurant_consulting", "m_and_a_consulting", "pricing_strategy_consulting", "brand_strategy_consulting", "saas_marketing_consulting", "done_for_you_services", "prop_firm_passing_service", "trading_account_management", "done_for_you_trading", "accounting_bookkeeping", "tax_preparation", "legal_services", "notary_services", "insurance_brokerage", "financial_planning_service", "real_estate_services", "property_management", "mortgage_brokerage", "immigration_services", "patent_trademark_services", "business_formation_services", "shell_company_formation", "payroll_services", "audit_services", "forensic_accounting", "actuarial_services", "appraisal_services", "mediation_arbitration", "bail_bond_services", "crowdfunding_platform", "essay_mill_paper_mill", "government_service_facilitation", "immigration_services_unlicensed", "licensed_legal_services", "personalized_tax_services", "private_investigation", "repossession_services", "unlicensed_legal_services", "record_label", "book_publishing_house", "news_media_outlet", "radio_broadcasting", "tv_production_company", "film_studio", "magazine_publisher", "music_licensing_agency", "talent_management_agency", "advertising_network", "ad_tech_platform", "cleaning_service", "landscaping_service", "plumbing_service", "electrical_service", "hvac_service", "roofing_service", "painting_service", "moving_service", "handyman_service", "pest_control", "pool_service", "solar_installation", "home_renovation", "pressure_washing", "junk_removal", "garage_door_service", "fencing_service", "concrete_masonry", "tree_service", "window_cleaning", "gutter_service", "flooring_service", "cabinet_countertop", "home_inspection", "septic_service", "waterproofing_service", "insulation_service", "chimney_service", "locksmith_service", "glass_window_service", "epoxy_coating", "private_security_guard_service", "armored_car_transport", "executive_protection_bodyguard", "event_security_service", "alarm_system_installation", "cctv_installation", "private_investigation_agency", "background_check_provider", "locksmith_commercial", "bounty_hunter_bail_enforcement", "personal_styling", "personal_chef", "personal_assistant_service", "tutoring_service", "pet_services", "wedding_planning", "concierge_service", "personal_training_service", "nanny_service", "elder_care_service", "errand_service", "life_organization", "relocation_service", "adult_dating_services", "escort_services", "hotel_accommodation_bookings", "mail_order_spouse", "psychic_fortune_telling", "timeshare_sales", "freight_brokerage", "courier_service", "warehousing_service", "last_mile_delivery", "auto_transport", "international_shipping", "cold_chain_logistics", "commercial_airline_tickets", "cruise_line_bookings", "contract_manufacturing", "cnc_machining_service", "3d_printing_service_commercial", "plastic_injection_molding", "metal_fabrication", "pcba_assembly", "chemical_manufacturing", "textile_manufacturing", "food_processing_facility", "packaging_manufacturing", "industrial_automation_integrator", "mining_and_extraction", "oil_and_gas_services", "renewable_energy_generation", "waste_management_recycling", "hazardous_waste_disposal", "aerospace_defense_contracting", "personal_training_studio", "nutrition_consulting", "mental_health_counseling", "physical_therapy_service", "occupational_therapy_service", "speech_therapy_service", "chiropractic_service", "acupuncture_service", "massage_therapy_service", "midwifery_doula", "lactation_consulting", "dietitian_service", "addiction_recovery_services", "dtc_lab_testing", "iv_therapy_infusion", "medspa_aesthetic_services", "prescription_delivery_services", "registered_dietitian_services", "unlicensed_therapy_counseling", "streetwear", "athleisure", "luxury_fashion", "kids_clothing", "custom_apparel", "workwear", "swimwear", "lingerie_intimates", "vintage_clothing", "plus_size_fashion", "maternity_clothing", "sleepwear_loungewear", "denim_brand", "outerwear_jackets", "socks_hosiery", "costumes_cosplay", "scrubs_medical_apparel", "dance_performance_wear", "hunting_camo_apparel", "casual_everyday_clothing", "protein_supplements", "vitamins_minerals", "pre_workout", "nootropics", "herbal_supplements", "weight_management_supplements", "gut_health", "cbd_products", "mushroom_supplements", "collagen_supplements", "testosterone_boosters", "sleep_supplements", "immune_support", "joint_bone_health", "greens_powder", "creatine_supplements", "electrolyte_hydration", "prenatal_supplements", "kids_supplements", "pet_supplements", "ayurvedic_supplements", "keto_supplements", "cannabis_thc_products", "cbd_hemp_products_compliant", "delta8_thc_products", "dietary_supplements", "drug_precursor_chemicals", "illegal_drugs", "kratom_kava_products", "medical_treatment_claims_product", "nutraceutical_products", "otc_medication_sales", "performance_enhancing_drugs", "research_chemicals_dangerous", "research_peptides", "sexual_enhancement_products", "tobacco_products", "unlicensed_rx_sales", "skincare", "haircare", "cosmetics_makeup", "mens_grooming", "fragrance", "oral_care", "sunscreen_spf", "hair_growth_products", "body_care", "deodorant", "lip_care", "acne_treatment", "men_skincare", "baby_skincare", "tattoo_aftercare", "intimate_care", "home_gym_equipment", "yoga_equipment", "combat_sports_gear", "outdoor_fitness_gear", "wearable_fitness", "recovery_equipment", "weightlifting_equipment", "cardio_equipment", "gymnastics_equipment", "swimming_gear", "jump_rope_equipment", "grip_strength_tools", "sauna_cold_plunge", "posture_correctors", "jewelry", "sunglasses_eyewear", "bags_wallets", "hats_headwear", "phone_accessories", "travel_accessories", "scarves_wraps", "belts", "hair_accessories", "tech_accessories", "keychains_charms", "custom_engraved_accessories", "cannabis_accessories_non_drug", "drug_paraphernalia", "high_value_goods_over_500", "precious_metals_stones", "replica_counterfeit_goods", "home_decor", "candles_scents", "kitchenware", "bedding_linens", "smart_home", "cleaning_products", "outdoor_furniture", "organization_storage", "wall_art_prints", "rugs_carpets", "lighting_fixtures", "planters_garden_decor", "bathroom_accessories", "luxury_home_goods", "seasonal_holiday_decor", "pet_home_products", "home_fragrance_diffusers", "hazardous_chemicals_b2c", "pre_orders_delayed_delivery", "audio_equipment", "camera_equipment", "gaming_hardware", "drones_robotics", "ev_accessories", "charging_power", "smart_wearables", "home_security_devices", "3d_printers", "projectors_displays", "streaming_devices", "vr_headsets", "e_readers", "portable_tech", "hardware_wallets", "regulated_medical_devices", "signal_jamming_devices", "spy_cameras_hidden_recording", "specialty_coffee_tea", "health_food", "snacks_treats", "sauces_condiments", "alcohol_spirits", "meal_kits", "baked_goods", "beverages", "pet_food_treats", "protein_bars_snacks", "jerky_meat_snacks", "chocolate_confections", "honey_sweeteners", "olive_oil_vinegar", "hot_sauce", "dried_fruit_nuts", "baby_food", "plant_based_food", "gluten_free_food", "keto_food_products", "subscription_food_box", "kombucha_fermented", "alcohol_sales", "baby_products", "kids_toys", "kids_educational", "baby_clothing_accessories", "nursery_decor", "kids_outdoor_play", "kids_books", "baby_safety_products", "kids_arts_crafts", "camping_hiking", "fishing_gear", "hunting_gear", "cycling_gear", "water_sports_gear", "golf_equipment", "snow_sports_gear", "climbing_gear", "archery_equipment", "skateboarding_gear", "pickleball_equipment", "tennis_equipment", "equestrian_gear", "tactical_gear", "overlanding_gear", "explosives_fireworks", "firearms_sales", "self_defense_products", "weapon_components", "craft_kits", "sewing_textiles", "stationery", "scrapbooking_supplies", "beading_jewelry_supplies", "pottery_supplies", "printmaking_supplies", "car_accessories", "detailing_products", "motorcycle_gear", "truck_accessories", "off_road_parts", "car_audio_electronics", "performance_parts", "car_care_products", "ev_charging_accessories", "auto_repair_service", "auto_body_shop", "car_dealership", "car_wash", "tire_shop", "oil_change_shop", "auto_parts_store", "motorcycle_shop", "ev_charging_station", "transmission_shop", "muffler_exhaust_shop", "auto_glass_shop", "auto_upholstery_shop", "car_audio_shop", "smog_emissions_shop", "truck_repair_shop", "rv_repair_shop", "boat_repair_shop", "used_car_lot", "auto_auction", "dog_products", "cat_products", "aquarium_supplies", "bird_supplies", "reptile_supplies", "horse_supplies", "pet_apparel", "pet_tech", "pet_grooming_products", "hand_tools", "power_tools_and_accessories", "hardware_and_fasteners", "workshop_equipment_and_storage", "safety_and_work_gear", "painting_and_building_supplies", "office_supplies", "desk_accessories", "printing_supplies", "shipping_packaging", "reusable_products", "solar_powered_products", "christian_books_bibles", "christian_apparel", "christian_jewelry", "christian_home_decor", "jewish_judaica", "jewish_books_torah", "jewish_apparel", "islamic_books_quran", "islamic_apparel", "islamic_prayer_goods", "hindu_puja_supplies", "hindu_books_texts", "buddhist_meditation_goods", "buddhist_books_texts", "sikh_religious_goods", "other_religious_products", "handmade_goods_marketplace", "vintage_resale_marketplace", "electronics_marketplace", "auto_parts_marketplace", "luxury_goods_marketplace", "collectibles_marketplace", "wholesale_marketplace", "local_goods_marketplace", "sneaker_marketplace", "book_marketplace", "furniture_marketplace", "musical_instrument_marketplace", "art_marketplace", "ticket_marketplace", "industrial_equipment_marketplace", "craft_supply_marketplace", "baby_kids_marketplace", "outdoor_gear_marketplace", "pet_marketplace", "sustainable_goods_marketplace", "cultural_artifacts_looted", "dropshipping_operations", "endangered_animal_products", "human_body_parts_tissue", "nft_marketplace", "penny_auction", "primary_event_ticketing", "freelancer_marketplace", "home_services_marketplace", "tutoring_marketplace", "legal_services_marketplace", "healthcare_marketplace", "wedding_services_marketplace", "creative_and_content_creation_marketplace", "beauty_services_marketplace", "fitness_trainer_marketplace", "pet_services_marketplace", "childcare_marketplace", "elder_care_marketplace", "translation_marketplace", "coaching_marketplace", "therapy_marketplace", "photography_marketplace", "dj_entertainment_marketplace", "auto_services_marketplace", "freelance_marketplace_operator", "equipment_rental_marketplace", "vehicle_rental_marketplace", "space_rental_marketplace", "vacation_rental_marketplace", "clothing_rental_marketplace", "camera_gear_rental", "rv_camper_rental", "boat_rental_marketplace", "storage_rental_marketplace", "office_coworking_rental", "parking_rental_marketplace", "restaurant_marketplace", "grocery_marketplace", "catering_marketplace", "homemade_food_marketplace", "meal_prep_marketplace", "bakery_marketplace", "farm_produce_marketplace", "chef_booking_marketplace", "course_marketplace", "template_marketplace", "stock_media_marketplace", "music_beats_marketplace", "ebook_marketplace", "plugin_theme_marketplace", "3d_model_marketplace", "prompt_marketplace", "code_snippet_marketplace", "affiliate_marketing_platform", "game_cheats_hacks", "weapon_blueprint_distribution", "saas_marketplace", "agency_marketplace", "manufacturing_marketplace", "logistics_marketplace", "commercial_real_estate_marketplace", "business_for_sale_marketplace", "food_delivery", "grocery_delivery", "package_delivery", "moving_labor", "alcohol_delivery", "pharmacy_delivery", "flower_delivery_gig", "furniture_delivery_gig", "catering_delivery", "rideshare", "chauffeur_service", "bike_scooter_rental", "boat_charter_gig", "moving_truck_rental_gig", "assembly_installation", "waiting_line_service", "personal_shopping", "grocery_shopping_gig", "gift_wrapping_gig", "notary_gig", "laundry_gig", "car_wash_gig", "cleaning_gig", "lawn_care_gig", "handyman_gig", "pet_care_gig", "childcare_gig", "elder_care_gig", "painting_gig", "snow_removal_gig", "pool_cleaning_gig", "organizing_gig", "pressure_washing_gig", "junk_removal_gig", "consulting_gig", "accounting_gig", "legal_gig", "healthcare_gig", "teaching_gig", "translation_gig", "data_entry_gig", "research_gig", "virtual_assistant_gig", "sales_gig", "recruiting_gig", "mystery_shopping", "focus_group_gig", "product_testing_gig", "drone_pilot_gig", "fitness_instruction_gig", "tour_guide_gig", "dating_community", "personal_development_community", "spirituality_community", "parenting_community", "travel_community", "networking_community", "faith_community", "mens_community", "womens_community", "expat_community", "adult_community_nsfw", "hate_violence_communities", "personal_fundraising", "political_fundraising", "political_organizations", "pornographic_content", "registered_501c3", "religious_organization", "unregistered_charities", "ai_outreach_tool", "ai_chatbot_software", "ai_writing_tool", "ai_image_generator", "ai_video_tool", "ai_voice_tool", "ai_data_analysis", "ai_code_assistant", "ai_meeting_assistant", "workflow_automation_software", "ai_sales_tool", "ai_customer_support", "ai_recruiting_tool", "ai_translation_tool", "ai_music_tool", "ai_presentation_tool", "ai_research_tool", "ai_seo_tool", "ai_social_media_tool", "ai_phone_agent", "ai_legal_tool", "ai_healthcare_tool", "llm_api_platform", "ai_agent_platform", "generative_ai_platform", "celebrity_impersonation", "deepfake_service", "ai_nsfw_content_generator", "ecommerce_platform", "product_research_tool", "price_tracker", "shipping_software", "print_on_demand_software", "marketplace_seller_tool", "resale_arbitrage_tool", "reseller_management_tool", "product_review_software", "returns_management", "product_feed_management", "checkout_optimization", "wholesale_ordering", "project_management_software", "team_communication", "video_conferencing", "document_collaboration", "time_tracking_software", "scheduling_software", "hr_software", "knowledge_base_software", "form_survey_builder", "note_taking_app", "task_management", "contract_management", "expense_management", "okr_goal_tracking", "employee_engagement", "onboarding_software", "applicant_tracking", "asset_management", "facility_management", "visitor_management", "community_platform", "event_management_software", "webinar_software", "school_management", "newsletter_platform", "podcast_hosting", "forum_software", "virtual_classroom", "restaurant_pos", "salon_software", "gym_management_software", "auto_shop_software", "legal_practice_software", "church_management", "nonprofit_software", "logistics_software", "agriculture_software", "field_service_software", "marina_management", "hotel_pms", "childcare_management", "cleaning_business_software", "roofing_software", "landscaping_software", "pest_control_software", "tattoo_studio_software", "cannabis_software", "password_manager", "cybersecurity_software", "identity_verification", "backup_recovery", "endpoint_protection", "email_security", "access_management", "compliance_software", "data_privacy_tool", "vpn_services", "people_search_tool", "game_mod_tool", "streaming_tool", "game_server_hosting", "music_software", "video_editing_software", "photo_editing_software", "animation_software", "audio_editing_software", "screen_recording_software", "sports_betting_tool", "fantasy_sports_paid_entry", "iptv_pirated_streaming", "loot_boxes_gacha", "skill_contests_free_entry", "skill_contests_paid_entry", "only_fans_management_software", "pornography_platform", "business_phone_system", "customer_messaging", "digital_key_reselling", "streaming_account_reselling", "subscription_account_sharing", "account_generation_tool", "primary_care_telehealth", "urgent_care_telehealth", "pediatric_telehealth", "geriatric_telehealth", "family_medicine_telehealth", "internal_medicine_telehealth", "preventive_care_telehealth", "licensed_online_pharmacy", "telemedicine_practitioner_services", "dermatology_telehealth", "acne_telehealth", "psoriasis_eczema_telehealth", "skin_cancer_screening_tele", "cosmetic_dermatology_tele", "therapy_telehealth", "psychiatry_telehealth", "addiction_telehealth", "couples_therapy_telehealth", "child_psychology_telehealth", "eating_disorder_telehealth", "ptsd_trauma_telehealth", "adhd_telehealth", "anxiety_depression_telehealth", "ocd_telehealth", "grief_counseling_telehealth", "anger_management_telehealth", "family_therapy_telehealth", "group_therapy_telehealth", "licensed_psychedelic_therapy", "womens_health_telehealth", "mens_health_telehealth", "sexual_health_telehealth", "fertility_telehealth", "hormone_therapy_telehealth", "menopause_telehealth", "prenatal_telehealth", "postpartum_telehealth", "erectile_dysfunction_tele", "hair_loss_telehealth", "birth_control_telehealth", "sti_testing_telehealth", "dental_telehealth", "orthodontics_telehealth", "optometry_telehealth", "oral_surgery_consultation", "vision_therapy_telehealth", "cardiology_telehealth", "endocrinology_telehealth", "neurology_telehealth", "orthopedic_telehealth", "allergy_telehealth", "ent_telehealth", "rheumatology_telehealth", "gastroenterology_telehealth", "infectious_disease_telehealth", "pulmonology_telehealth", "nephrology_telehealth", "oncology_telehealth", "hematology_telehealth", "urology_telehealth", "weight_management_telehealth", "glp1_weight_loss_tele", "diabetes_management_tele", "metabolic_health_tele", "bariatric_telehealth", "physical_therapy_telehealth", "occupational_therapy_tele", "speech_therapy_telehealth", "pain_management_telehealth", "cardiac_rehab_telehealth", "pelvic_floor_telehealth", "vestibular_telehealth", "sleep_medicine_telehealth", "chronic_disease_management", "chronic_pain_telehealth", "migraine_telehealth", "asthma_copd_telehealth", "nutrition_telehealth", "naturopathic_telehealth", "functional_medicine_telehealth", "acupuncture_telehealth", "health_coaching_telehealth", "integrative_medicine_tele", "ayurvedic_telehealth", "genetic_counseling_telehealth", "pharmacogenomics_tele", "rare_disease_telehealth", "second_opinion_telehealth", "vet_telehealth", "pet_behavior_telehealth", "exotic_pet_telehealth", "equine_telehealth", "veterinary_services", "class_action_settlement", "mastermind_event", "webinar_event", "virtual_summit", "bootcamp_event", "workshop_seminar", "hackathon", "corporate_training_event", "training_certification_event", "convention_expo", "conference_summit", "industry_awards_event", "product_launch_event", "investor_demo_day", "panel_discussion_event", "pitch_competition", "meetup_event", "dinner_event", "alumni_event", "community_gathering", "singles_event", "professional_happy_hour", "women_networking_event", "founders_dinner", "industry_mixer", "concert_event", "comedy_show", "theater_performance", "film_screening", "music_festival", "cultural_festival", "fashion_show", "drag_show", "magic_show", "dance_performance", "poetry_spoken_word", "art_exhibition", "party_event", "trivia_night", "wine_tasting_event", "beer_festival", "car_show", "food_festival", "fitness_challenge_event", "marathon_race", "tournament_event", "fight_event", "yoga_retreat_event", "outdoor_adventure_event", "esports_tournament", "obstacle_course_race", "cycling_event", "swim_meet", "golf_tournament", "pickleball_tournament", "crossfit_competition", "martial_arts_tournament", "surfing_competition", "wellness_retreat", "spiritual_retreat", "couples_retreat", "plant_medicine_retreat", "luxury_experience_event", "detox_retreat", "silent_retreat", "creative_retreat", "leadership_retreat", "mens_retreat", "womens_retreat", "digital_detox_retreat", "fundraiser_event", "awareness_event", "volunteer_event", "charity_auction", "benefit_concert", "charity_run_walk", "environmental_cleanup", "family_festival", "kids_event", "holiday_event", "farmers_market_event", "block_party", "graduation_ceremony", "memorial_event", "stock_market_newsletter", "crypto_newsletter", "personal_finance_newsletter", "real_estate_newsletter", "fintech_newsletter", "venture_capital_newsletter", "options_trading_newsletter", "forex_newsletter", "macro_economics_newsletter", "alternative_investing_newsletter", "tax_strategy_newsletter", "ai_newsletter", "tech_industry_newsletter", "cybersecurity_newsletter", "developer_newsletter", "product_newsletter", "devops_newsletter", "open_source_newsletter", "robotics_newsletter", "climate_tech_newsletter", "travel_newsletter", "fashion_newsletter", "parenting_newsletter", "sports_newsletter", "gaming_newsletter", "music_entertainment_newsletter", "book_reading_newsletter", "dating_relationships_newsletter", "home_design_newsletter", "pet_newsletter", "wine_spirits_newsletter", "automotive_newsletter", "political_newsletter", "geopolitics_newsletter", "media_journalism_newsletter", "defense_security_newsletter", "legal_policy_newsletter", "design_newsletter", "education_newsletter", "science_newsletter", "philosophy_newsletter", "sustainability_newsletter", "architecture_newsletter", "history_newsletter", "psychology_newsletter", "career_newsletter", "spirituality_newsletter", "self_improvement_newsletter", "productivity_newsletter", "faith_newsletter", "gym_facility", "crossfit_box", "yoga_studio", "pilates_studio", "martial_arts_gym", "boxing_gym", "climbing_gym", "dance_studio", "swimming_pool", "sports_facility", "golf_course", "bowling_alley", "skating_rink", "trampoline_park", "tennis_club", "pickleball_facility", "gymnastics_center", "spin_studio", "barre_studio", "personal_training_studio_bm", "recovery_studio", "indoor_soccer", "batting_cage", "shooting_range", "archery_range", "equestrian_center", "fine_dining", "fast_casual_restaurant", "steakhouse", "seafood_restaurant", "pizza_shop", "sushi_restaurant", "deli_sandwich_shop", "bbq_restaurant", "mexican_restaurant", "italian_restaurant", "chinese_restaurant", "indian_restaurant", "thai_restaurant", "korean_restaurant", "mediterranean_restaurant", "vegan_vegetarian_restaurant", "brunch_restaurant", "ramen_noodle_shop", "poke_bowl_shop", "ethnic_restaurant", "coffee_shop_cafe", "bakery", "juice_smoothie_bar", "ice_cream_shop", "donut_shop", "bubble_tea_shop", "food_truck", "fast_food", "ghost_kitchen", "food_hall_vendor", "catering_kitchen", "butcher_shop", "cheese_shop", "farmers_market_stall", "bar_lounge", "brewery_taproom", "winery_tasting", "wine_bar", "cocktail_bar", "sports_bar", "hookah_lounge", "distillery", "commercial_farming", "livestock_ranching", "hydroponic_vertical_farming", "forestry_logging", "aquaculture_fisheries", "vineyard_winery_production", "cannabis_cultivation", "hemp_farming", "grain_production", "agricultural_cooperative", "fertilizer_pesticide_sales", "farm_equipment_sales", "boutique_store", "clothing_store", "shoe_store", "jewelry_store", "electronics_store", "bookstore", "pet_store", "toy_store", "sporting_goods_store", "thrift_store", "smoke_shop", "cannabis_dispensary", "convenience_store", "grocery_store", "liquor_store", "florist", "gift_shop", "furniture_store", "home_improvement_store", "art_gallery_retail", "music_instrument_store", "outdoor_recreation_store", "phone_repair_store", "watch_store", "bridal_shop", "maternity_store", "kids_store", "sneaker_store", "vintage_store", "comic_book_store", "record_store", "craft_supply_store", "fabric_store", "health_food_store", "vitamin_supplement_store", "optical_store", "mattress_store", "appliance_store", "kitchen_bath_store", "tile_flooring_store", "paint_store", "garden_center", "gun_store", "pawn_shop", "dollar_store", "hair_salon", "nail_salon", "day_spa", "med_spa", "massage_studio", "tattoo_parlor", "tanning_salon", "beauty_supply_store", "lash_brow_studio", "waxing_studio", "sauna_bathhouse", "cryotherapy_studio", "float_sensory_studio", "iv_therapy_lounge", "teeth_whitening_studio", "microblading_studio", "spray_tan_studio", "blowout_bar", "mens_barbershop", "kids_salon", "medical_office", "dental_office", "chiropractic_office", "physical_therapy_clinic", "optometry_office", "dermatology_clinic", "urgent_care_clinic", "pharmacy", "veterinary_clinic", "mental_health_clinic", "fertility_clinic", "acupuncture_clinic", "hearing_aid_center", "orthopedic_clinic", "pediatric_clinic", "cosmetic_surgery_center", "allergy_clinic", "pain_management_clinic", "dialysis_center", "imaging_center", "lab_testing_center", "sleep_clinic", "weight_loss_clinic", "hormone_therapy_clinic", "addiction_treatment_center", "rehabilitation_center", "occupational_therapy_clinic", "speech_therapy_clinic", "wound_care_center", "funeral_home_mortuary", "crematory_service", "cemetery_memorial_park", "casket_urn_retailer", "pet_cremation_service", "biohazard_cleanup", "estate_liquidation", "hotel", "motel", "boutique_hotel", "bed_and_breakfast", "hostel", "resort", "campground_rv", "vacation_rental_property", "extended_stay", "glamping_site", "cabin_rental", "eco_lodge", "retreat_center", "tutoring_center", "daycare_center", "preschool", "learning_center", "music_school", "art_school", "driving_school", "language_school", "trade_school", "coding_bootcamp_location", "montessori_school", "after_school_program", "swim_school", "cooking_school", "test_prep_center", "special_needs_center", "adult_education_center", "flight_school", "cosmetology_school", "movie_theater", "escape_room", "arcade", "mini_golf", "laser_tag", "go_kart", "amusement_park", "museum", "zoo_aquarium", "theater_venue", "nightclub", "karaoke_bar", "comedy_club", "live_music_venue", "axe_throwing", "virtual_reality_arcade", "board_game_cafe", "cat_cafe", "haunted_house", "water_park", "indoor_playground", "concert_venue", "drive_in_theater", "billiards_hall", "dart_bar", "indoor_skydiving", "law_office", "real_estate_office", "insurance_office", "accounting_office", "bank_credit_union", "printing_shop", "shipping_center", "dry_cleaner", "laundromat", "storage_facility", "coworking_space", "check_cashing", "title_company", "travel_agency_storefront", "staffing_office", "financial_advisor_office", "immigration_office", "bail_bonds_office", "pet_grooming", "dog_daycare", "pet_boarding", "dog_training_facility", "pet_spa", "aquatic_pet_store", "pet_bakery", "pet_photography_studio", "plumbing_showroom", "hvac_showroom", "solar_showroom", "kitchen_design_showroom", "bath_design_showroom", "window_door_showroom", "pool_spa_showroom", "fireplace_showroom", "countertop_showroom", "nonprofit_organization", "charity_foundation", "political_campaign", "community_organization", "environmental_nonprofit", "education_nonprofit", "health_nonprofit", "animal_welfare_nonprofit", "arts_culture_nonprofit", "social_justice_nonprofit", "veterans_nonprofit", "youth_nonprofit", "disaster_relief_nonprofit", "food_bank", "housing_nonprofit", "government_agency", "public_utility", "public_library", "public_school", "municipal_service", "military_installation", "embassy_consulate", "niche_service", "niche_product", "hybrid_business", "other_general", "holding_company", "family_office", "cooperative", "social_enterprise", "incubator_accelerator", "coworking_community", "media_company", "research_lab", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "invoice_prefix": { "description": "Prefix used for account invoices.", "example": "SHINE", "type": [ "string", "null" ] }, "logo_url": { "description": "Account logo image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "description": "Arbitrary key/value metadata supplied at account creation.", "example": { "external_id": "shop_4417", "region": "austin" }, "type": "object" }, "onboarding_type": { "description": "Type of onboarding the account has completed.", "enum": [ "platform", "seller", null ], "example": "seller", "type": [ "string", "null" ] }, "opengraph_image_url": { "description": "Account Open Graph image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "opengraph_image_variant": { "description": "Account Open Graph image variant.", "enum": [ "white", "black", "orange", null ], "example": "black", "type": [ "string", "null" ] }, "other_business_description": { "description": "Business type details when business_type is `other`.", "example": "Mobile auto detailing", "type": [ "string", "null" ] }, "other_industry_description": { "description": "Industry details when industry_type is `other`.", "example": "Automotive services", "type": [ "string", "null" ] }, "owner": { "$ref": "#/components/schemas/UserSummary", "description": "The single user who owns the account, whose email is the `email` above. Distinct from the `owner` role on team members, which any number of them can hold." }, "parent_account": { "description": "Parent account for connected accounts, or `null` for standalone accounts.", "oneOf": [ { "$ref": "#/components/schemas/AccountParent" }, { "type": "null" } ] }, "payment_controls": { "description": "Payment health controls currently applied to the account. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise.", "oneOf": [ { "$ref": "#/components/schemas/AccountPaymentControls" }, { "type": "null" } ] }, "privacy_policy": { "description": "The account's privacy policy document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "product_tax_code": { "description": "Tax classification code applied by default to the account's products, with `id`, `name`, and `product_type`. `null` when no default is set.", "example": { "id": "ptc_xxxxxxxxxxxxxx", "name": "General - Digital Goods", "product_type": "digital" }, "type": [ "object", "null" ] }, "recommended_actions": { "deprecated": true, "description": "DEPRECATED: Use the `GET /recommended_actions?account_id={account_id}` endpoint instead.", "items": { "$ref": "#/components/schemas/AccountRecommendedAction", "description": "Deprecated: use the `GET /recommended_actions?account_id={account_id}` endpoint instead. Optional actions that unlock capabilities or grow the account, same shape as `required_actions`. Computed only on `retrieve` and `me`; `null` otherwise." }, "type": [ "array", "null" ] }, "require_2fa": { "description": "Whether authorized users must enable two-factor authentication.", "example": true, "type": "boolean" }, "required_actions": { "items": { "$ref": "#/components/schemas/AccountRequiredAction", "description": "Actions the account owner must take to unblock capabilities like payouts and card spend, ordered by display priority. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise." }, "type": [ "array", "null" ] }, "return_policy": { "description": "The account's return policy document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "route": { "description": "Account public route identifier.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this account.", "example": false, "type": "boolean" }, "show_joined_whops": { "description": "Whether the account appears in joined whops on other accounts.", "example": false, "type": "boolean" }, "show_reviews_dtc": { "description": "Whether reviews are displayed on direct-to-consumer product pages.", "example": false, "type": "boolean" }, "show_user_directory": { "description": "Whether the account shows users in the user directory.", "example": false, "type": "boolean" }, "social_links": { "items": { "$ref": "#/components/schemas/AccountSocialLink", "description": "Account social links." }, "type": "array" }, "stablecoin_rails": { "description": "Whether the account settles on stablecoin rails — its balance is held on-chain as USDT and paid out over crypto, rather than as fiat cash.", "example": false, "type": "boolean" }, "status": { "description": "Whether the account can operate on Whop: `active` or `suspended`. Computed on `list`, `retrieve`, `me`, and `suspend`; `null` otherwise.", "example": "active", "type": [ "string", "null" ] }, "status_reason": { "description": "Why the account was suspended, in language safe to show the account owner. Computed on `retrieve`, `me`, and `suspend`; `null` otherwise, when `status` is not `suspended`, and when the suspension was recorded without a reason.", "example": "Payments are paused while we review recent chargebacks on this account.", "type": [ "string", "null" ] }, "store_page_config": { "$ref": "#/components/schemas/AccountStorePageConfig", "description": "Account store page display configuration." }, "target_audience": { "description": "Target audience for this account.", "example": "Owners of new and enthusiast vehicles in Austin, TX", "type": [ "string", "null" ] }, "tax_collection_enabled_states": { "items": { "description": "US state codes (of the 50 states plus `DC`) where the account collects tax: the full set when Whop remits (`tax_remitted_by` `whop`), the configured subset when the account self-remits (`self`), and empty when neither. On update, send the complete list to replace it (only allowed when `self`).", "example": "TX", "type": "string" }, "type": "array" }, "tax_identifiers": { "items": { "$ref": "#/components/schemas/AccountTaxIdentifier", "description": "Account tax/VAT registrations. Empty when none are set." }, "type": "array" }, "tax_remitted_by": { "description": "Who calculates and remits tax for the account: `whop` (Whop calculates and remits), `self` (Whop calculates; the account collects and remits), or `none` (neither; the account is responsible). `null` until the account enrolls in the Whop tax service.", "enum": [ "whop", "self", "none", null ], "example": "self", "type": [ "string", "null" ] }, "tax_type": { "description": "How tax is applied to the account's prices: `inclusive` (tax included in the listed price) or `exclusive` (tax added on top). Defaults to `exclusive` when unset; `null` only when the account has no payment connection.", "enum": [ "inclusive", "exclusive", null ], "example": "inclusive", "type": [ "string", "null" ] }, "terms_of_service": { "description": "The account's terms of service document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "three_ds_level": { "description": "Account-level 3D Secure behavior. `mandate_challenge` requires cardholder verification on supported card payments; `null` uses the standard checkout flow.", "enum": [ "mandate_challenge", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" }, "total_earned_usd": { "description": "Account lifetime sales, normalized to USD. Computed only on `retrieve` and `me` for callers with `stats:read` scope; `null` otherwise.", "example": 0.0, "type": [ "number", "null" ] }, "total_usd": { "description": "Total USD value across balances with known exchange rates. Computed only on single-account reads (`retrieve` and `me`); `null` on list responses, writes, missing balance-read permission, or unavailable balance source.", "example": "50.00", "type": [ "string", "null" ] }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image.", "example": true, "type": "boolean" }, "verification": { "description": "Account identity verification status for the `individual` (KYC) and `business` (KYB) profiles. Each is `null` until created, otherwise a `status` of `not_started`, `pending`, `manual_review`, `approved`, or `rejected`.", "example": { "business": null, "individual": null }, "type": "object" }, "volume_usd": { "description": "Lifetime volume through the account — sales plus transfers received — normalized to USD. Computed only on `list` for callers with `stats:read` on the account; `null` otherwise.", "type": [ "number", "null" ] }, "wallet": { "description": "Account primary crypto wallet, or `null` if none has been provisioned.", "oneOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ] } }, "required": [ "id", "email", "title", "description", "route", "logo_url", "banner_image_url", "terms_of_service", "privacy_policy", "return_policy", "eula", "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", "three_ds_level", "collect_vat_id", "target_audience", "send_customer_emails", "show_joined_whops", "show_reviews_dtc", "show_user_directory", "store_page_config", "metadata", "created_at", "use_logo_as_opengraph_image_fallback", "total_earned_usd", "status", "status_reason", "volume_usd", "capabilities", "payment_controls", "cards", "required_actions", "recommended_actions", "tax_remitted_by", "tax_type", "product_tax_code", "business_address", "business_name", "tax_identifiers", "tax_collection_enabled_states", "total_usd", "balances", "stablecoin_rails", "can_transfer_pending_balance_to_children", "verification", "company_formation", "owner", "parent_account", "wallet", "social_links" ], "type": "object" }, "AccountBalanceBreakdown": { "properties": { "available": { "description": "Amount you can spend, send, or withdraw now, in native units, as a decimal string.", "example": "1500.0", "type": "string" }, "in_transit": { "description": "Amount moving between the account's own destinations, such as a treasury sweep to its crypto wallet or a card top-up. In native units, as a decimal string.", "example": "0", "type": "string" }, "pending": { "description": "Amount from recent payments still settling, in native units, as a decimal string.", "example": "0", "type": "string" }, "pending_settlements": { "items": { "$ref": "#/components/schemas/AccountBalanceSettlement", "description": "When the pending amount is expected to settle, one entry per day, earliest first. Money with no scheduled settlement day, such as a transfer in flight, is left out — so these can sum to less than `pending`, never more." }, "type": "array" }, "reserve": { "description": "Amount held back, in native units, as a decimal string. Retrieve the account's reserves for why it is held and when it unlocks.", "example": "0", "type": "string" } }, "required": [ "available", "pending", "in_transit", "reserve", "pending_settlements" ], "type": "object" }, "AccountBalanceSettlement": { "properties": { "amount": { "description": "Amount expected that day, in native units, as a decimal string.", "example": "12.5", "type": "string" }, "date": { "description": "The day this money is expected to finish settling, as an ISO 8601 date.", "example": "2026-01-01", "type": "string" } }, "required": [ "date", "amount" ], "type": "object" }, "AccountBalanceToken": { "properties": { "balance": { "description": "Total amount held in native units, as a decimal string.", "example": "50.0", "type": "string" }, "breakdown": { "$ref": "#/components/schemas/AccountBalanceBreakdown", "description": "Balance split into available, pending, and reserve amounts, as native-unit decimal strings, with the days the pending amount is expected to settle. On-chain crypto is entirely available; good_funds and fiat cash can have pending or reserve portions." }, "icon_url": { "description": "Holding icon URL.", "example": "https://assets.whop.com/tokens/usd.png", "type": [ "string", "null" ] }, "name": { "description": "The holding's display name", "example": "US Dollar", "type": "string" }, "price_usd": { "description": "USD price per unit, or `null` when no exchange rate is available.", "example": 1.0, "type": [ "number", "null" ] }, "symbol": { "description": "Holding display symbol, such as `USDT`, `cbBTC`, or `EUR`.", "example": "USD", "type": "string" }, "value_usd": { "description": "Holding USD value, or `null` when no exchange rate is available.", "example": "50.00", "type": [ "string", "null" ] } }, "required": [ "symbol", "name", "balance", "value_usd", "price_usd", "icon_url", "breakdown" ], "type": "object" }, "AccountCapabilities": { "properties": { "accept_bank_payments": { "description": "Bank payins: debits, transfers, and local bank rails", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "accept_bnpl_payments": { "description": "Buy-now-pay-later payins; requires approval", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "accept_card_payments": { "description": "Card payins, including Apple Pay and Google Pay", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "bank_deposit": { "description": "Deposits by bank wire or ACH to the account's virtual bank account", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "card_deposit": { "description": "Balance top-ups by charging a stored payment method", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "card_issuing": { "description": "Issuing Whop cards; requires card application approval", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "crypto_deposit": { "description": "On-chain deposits to the account's crypto wallet", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "crypto_payout": { "description": "On-chain payouts to a crypto wallet", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "instant_payout": { "description": "Instant payouts to an eligible payout destination", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "run_ads": { "description": "Launching ad campaigns through Whop Ads. `inactive` while a requested ads services agreement is awaiting the account's signature.", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "standard_payout": { "description": "Standard payouts to an external payout destination", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "transfer": { "description": "Transfers to other accounts", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" } }, "required": [ "accept_card_payments", "accept_bank_payments", "accept_bnpl_payments", "standard_payout", "instant_payout", "crypto_payout", "transfer", "bank_deposit", "crypto_deposit", "card_deposit", "card_issuing", "run_ads" ], "type": "object" }, "AccountCards": { "properties": { "kind": { "description": "Whether the card application verifies a business (`business`, KYB) or a person (`individual`, consumer identity). `null` when the application is not yet linked to a verification.", "enum": [ "individual", "business", null ], "example": "individual", "type": [ "string", "null" ] }, "status": { "description": "Where the card application stands. `approved` means cards can be issued. `needs_verification` means the applicant has not completed identity verification yet; `needs_information` means they did, but the documents were rejected for a fixable reason and must be resubmitted. `pending` and `manual_review` are in flight. `denied`, `locked`, and `canceled` are terminal.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "approved", "type": "string" } }, "required": [ "kind", "status" ], "type": "object" }, "AccountCompanyFormation": { "additionalProperties": true, "properties": { "documents": { "items": { "$ref": "#/components/schemas/AccountCompanyFormationDocument", "description": "Formation documents available for download, such as the Articles of Organization and the EIN confirmation letter. Present once `status` leaves `draft`." }, "type": "array" }, "ein_registered": { "description": "Whether the company's EIN has been issued by the IRS. Present once `status` leaves `draft`.", "example": false, "type": "boolean" }, "legal_name": { "description": "Registered company name including the entity ending, for example `Acme, LLC`. Present once `status` leaves `draft`.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "signatures": { "$ref": "#/components/schemas/AccountCompanyFormationSignatures", "description": "IRS forms still awaiting a founder's signature, each with a hosted signing URL. Present once `status` leaves `draft`; empty when nothing needs signing." }, "state_registered": { "description": "Whether the state formation filing is complete. Present once `status` leaves `draft`.", "example": true, "type": "boolean" }, "status": { "enum": [ "draft", "processing", "filed", "rejected", "completed" ], "type": "string" } }, "required": [], "type": "object" }, "AccountCompanyFormationDocument": { "properties": { "id": { "description": "Document ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable document name, such as `Articles of Organization`.", "example": "Articles of Organization", "type": "string" }, "type": { "description": "Document category: `articles_of_organization`, `operating_agreement`, `ein_letter`, `signed_ss4`, `signed_form8821`, or `mail` for postal correspondence received on the company's behalf.", "example": "articles_of_organization", "type": "string" }, "url": { "description": "CDN URL for downloading the document.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/audio/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "name", "type", "url" ], "type": "object" }, "AccountCompanyFormationSignatureRequest": { "properties": { "expires_at": { "description": "When the signing URL expires, as an ISO 8601 timestamp. Present while `status` is `pending`.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "`pending` when a signing session is ready for the founder; `unknown` when the signature state could not be determined.", "enum": [ "pending", "unknown" ], "example": "pending", "type": "string" }, "url": { "description": "Hosted signing URL where the founder completes the form. Present while `status` is `pending`.", "example": "https://sign.doola.com/shine-time-auto-detailing/form8821", "type": "string" } }, "required": [ "status" ], "type": "object" }, "AccountCompanyFormationSignatures": { "additionalProperties": true, "properties": { "form8821": { "$ref": "#/components/schemas/AccountCompanyFormationSignatureRequest", "description": "Signature state for IRS Form 8821, the tax information authorization. Present only while the form still needs the founder's action." }, "ss4": { "$ref": "#/components/schemas/AccountCompanyFormationSignatureRequest", "description": "Signature state for IRS Form SS-4, the EIN application. Present only while the form still needs the founder's action." } }, "required": [], "type": "object" }, "AccountDisputeAlertAutoRefundControl": { "properties": { "locked": { "description": "Whether the account owner is prevented from changing this threshold.", "example": false, "type": "boolean" }, "threshold_usd": { "description": "Maximum dispute alert amount automatically refunded in USD. `null` when automatic refunds are disabled.", "example": 500, "type": [ "number", "null" ] } }, "required": [ "threshold_usd", "locked" ], "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/verify-identity/biz_xxxxxxxxx/", "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" }, "AccountParent": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Account public route identifier.", "example": "shine-time-holdings", "type": "string" }, "title": { "description": "Account display name.", "example": "Shine Time Holdings", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "AccountPaymentControls": { "properties": { "dispute_alert_auto_refund": { "$ref": "#/components/schemas/AccountDisputeAlertAutoRefundControl", "description": "Automatic refund settings for pre-chargeback dispute alerts." }, "dispute_alert_fee_usd": { "description": "Fee charged for each dispute alert in USD. `null` when unavailable.", "example": 29, "type": [ "number", "null" ] }, "enforce_3ds": { "description": "Whether 3-D Secure is forced on every card payment at checkout. The account cannot bypass it while set.", "example": false, "type": "boolean" }, "financing_disabled": { "description": "Whether payment health controls explicitly disable financing. This is independent of financing approval in `capabilities.accept_bnpl_payments`.", "example": false, "type": "boolean" }, "high_risk_processing_fee_percentage": { "description": "Additional processing fee percentage for high-risk processing.", "example": 0, "type": "number" }, "pending_auto_topup_fee_percentage": { "description": "Percentage fee charged when pending, not-yet-settled balance is advanced to fund the account's cards balance, where `2` means 2%. `0` when the account is exempt.", "example": 2.0, "type": "number" }, "pending_balance_delay_days": { "description": "Additional days payments remain pending before becoming available.", "example": 0, "type": "integer" }, "reserve": { "$ref": "#/components/schemas/AccountReserveControl", "description": "Reserve currently applied to incoming payment volume." }, "resolution_center_auto_refund": { "$ref": "#/components/schemas/AccountResolutionCenterAutoRefundControl", "description": "Automatic refund settings for resolution center cases." }, "restricted_payment_methods": { "items": { "description": "Card brands blocked at checkout for this account. Empty when none are blocked. The account cannot re-enable them itself.", "enum": [ "card_visa", "card_mastercard", "card_american_express", "card_discover_global_network" ], "example": "card_visa", "type": "string" }, "type": "array" }, "undated_pending_reason": { "description": "Why pending funds without a settlement date aren't moving yet, when it's something the merchant can act on. `null` when there's no reason to show (still clearing, or the account is held for a reason that isn't merchant-actionable).", "enum": [ "kyc_incomplete", "pending_information_request", null ], "example": "pending_information_request", "type": [ "string", "null" ] }, "withdrawal_schedule": { "$ref": "#/components/schemas/AccountWithdrawalScheduleControl", "description": "How the account's balance automatically withdraws." } }, "required": [ "dispute_alert_auto_refund", "resolution_center_auto_refund", "dispute_alert_fee_usd", "high_risk_processing_fee_percentage", "pending_auto_topup_fee_percentage", "pending_balance_delay_days", "financing_disabled", "reserve", "withdrawal_schedule", "undated_pending_reason", "enforce_3ds", "restricted_payment_methods" ], "type": "object" }, "AccountPreferences": { "properties": { "ads_agreement": { "description": "The account's Whop Ads services and payment authorization agreement. `status` is `not_required`, `pending_signature` (a signature has been requested and campaign launch is blocked until it is provided), or `signed`. While pending, read the fields to answer from `GET /verifications/{id}` and sign by submitting them via `PATCH /verifications/{id}`.", "type": "object" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when it fails. Each entry has a `type` of `platform_balance` (id `ldgr_`) or `card` (id `payt_`), plus display fields so the configured source renders even for a viewer who doesn't own it. `backup` is `null` when only one method is configured. `null` until ads billing has been configured.", "type": [ "object", "null" ] }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Defaults to `America/New_York` until explicitly overridden.", "type": "string" }, "ads_triple_whale_integration": { "description": "The account's Triple Whale integration, which pushes Whop ad spend to Triple Whale's Data-In API so it reports as a `whop` channel. `status` is `connected`, `not_connected`, or `requires_shopify_store` (Triple Whale keys records by Shopify shop, so spend only flows while a store is connected). `masked_api_key` shows the leading characters of the stored key; the full key is never returned. `shop_domain` is the Shopify store spend is reported for.", "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. `false` when the account has no cards balance.", "type": "boolean" }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "type": "boolean" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_triple_whale_integration", "cards_auto_top_up", "dispute_fighter_enabled" ], "type": "object" }, "AccountRecommendedAction": { "properties": { "action": { "description": "The recommendation; new values may be added, so handle unknown actions gracefully", "enum": [ "theme_business", "create_product", "create_plan", "verify_identity", "connect_affiliate_program", "create_promotion", "migrate_from_stripe", "accept_first_payment", "launch_first_ad", "launch_draft_campaign", "increase_ad_budget", "refresh_ad_creatives", "fix_ad_billing", "exclude_customers_from_ads", "retarget_abandoned_checkouts", "fix_funnel_dropoff", "invite_team_member", "enable_tax_collection", "create_card", "apply_for_financing" ], "example": "apply_for_financing", "type": "string" }, "blocked_capabilities": { "items": { "description": "Capabilities this would unlock, or empty", "example": "accept_bnpl_payments", "type": "string" }, "type": "array" }, "cta": { "description": "The URL the call-to-action links to", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/settings/payments/", "type": "string" }, "cta_label": { "description": "Button label", "example": "Apply", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Let customers pay over time with buy now, pay later.", "type": "string" }, "icon_url": { "description": "Illustration icon URL, or `null`", "example": "https://whop.com/illustrations/orange/piggy-bank.svg", "type": [ "string", "null" ] }, "impact_score": { "description": "Estimated impact from 0-100, or `null` when not ranked", "example": 86, "type": [ "integer", "null" ] }, "reasoning": { "description": "Why this action was recommended, or `null`", "example": "Financing lifts conversion on the $249 ceramic coating, the priciest job on the menu.", "type": [ "string", "null" ] }, "status": { "description": "Always optional — never blocking", "enum": [ "optional" ], "example": "optional", "type": "string" }, "title": { "description": "Headline for the recommendation", "example": "Offer financing at checkout", "type": "string" } }, "required": [ "action", "status", "title", "description", "cta_label", "cta", "icon_url", "blocked_capabilities", "reasoning", "impact_score" ], "type": "object" }, "AccountRecommendedActionChain": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/AccountRecommendedActionChainStep", "description": "The chain's steps in run order" }, "type": "array" }, "description": { "description": "What running the chain accomplishes", "example": "Get your product in front of buyers", "type": "string" }, "id": { "description": "Chain ID — `rac_seed__` for seeded chains, `rac_chain_*` for generated ones", "example": "rac_chain_xxxxxxxxxxxx", "type": "string" }, "reasoning": { "description": "Why this chain was recommended, or `null` when unavailable", "example": { "summary": "No active campaigns yet" }, "type": [ "object", "null" ] }, "title": { "description": "Headline for the chain", "example": "Launch an ad campaign", "type": "string" } }, "required": [ "id", "title", "description", "reasoning", "actions" ], "type": "object" }, "AccountRecommendedActionChainStep": { "properties": { "action": { "description": "The action definition key this step runs; new values may be added, so handle unknown actions gracefully", "example": "create_ad_xxxxxxxxxxxxxx", "type": "string" }, "cta": { "description": "The URL where this step is done by hand", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/marketing/ads", "type": "string" }, "cta_label": { "description": "Button label", "example": "Create campaign", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Pick a budget", "type": "string" }, "error": { "description": "Why the step failed, or `null`", "type": [ "string", "null" ] }, "execution_type": { "description": "Whether the client should navigate to the CTA or open the programmatic execution dialog", "enum": [ "redirect", "programatic" ], "example": "redirect", "type": "string" }, "input": { "description": "The filled-in request body for the step's endpoint, or `null` when it was not recorded", "example": { "name": "Ceramic coating — Austin launch" }, "type": [ "object", "null" ] }, "output": { "description": "The API response the step produced, or `null` until it succeeds", "type": [ "object", "null" ] }, "position": { "description": "Zero-based order of this step within the chain", "example": 0, "type": "integer" }, "reasoning": { "description": "Why this step was recommended, or `null` when unavailable", "example": { "summary": "Create the campaign first" }, "type": [ "object", "null" ] }, "status": { "description": "Where the run step currently stands, or `null` when the chain has not been run", "enum": [ "pending", "redirected", "running", "succeeded", "failed", null ], "example": "pending", "type": [ "string", "null" ] }, "title": { "description": "Headline for the step", "example": "Create a campaign", "type": "string" } }, "required": [ "position", "action", "input", "output", "status", "error", "title", "description", "reasoning", "cta_label", "cta", "execution_type" ], "type": "object" }, "AccountRecommendedActionOutcome": { "properties": { "account": { "description": "The business the chain ran on.", "type": [ "object", "null" ] }, "actions": { "items": { "$ref": "#/components/schemas/AccountRecommendedActionChainStep", "description": "The chain's steps in run order, with inputs from ClickHouse and outputs from executions when present" }, "type": "array" }, "description": { "description": "What running the chain accomplishes", "type": "string" }, "executed_at": { "description": "When the chain was run, as an ISO 8601 timestamp.", "type": "string" }, "id": { "description": "The executed chain id (`rac_chain_*` or `rac_seed_*`)", "type": "string" }, "latency_ms": { "description": "Milliseconds from chain execution to that payment, or `null`.", "type": [ "integer", "null" ] }, "payment": { "description": "The payment amount as Money, or `null`.", "type": [ "object", "null" ] }, "payment_at": { "description": "When that payment completed, ISO 8601, or `null`.", "type": [ "string", "null" ] }, "payment_id": { "description": "The first `payment.completed` on that business after the chain, prefixed `pay_`, or `null` if none landed within 30 days.", "type": [ "string", "null" ] }, "reasoning": { "description": "Why this chain was recommended, or `null` when unavailable", "type": [ "object", "null" ] }, "title": { "description": "Headline for the chain", "type": "string" } }, "required": [ "id", "executed_at", "account", "payment_id", "payment_at", "payment", "latency_ms", "title", "description", "reasoning", "actions" ], "type": "object" }, "AccountRequiredAction": { "properties": { "action": { "description": "What the holder must do; new values may be added, so handle unknown actions gracefully", "enum": [ "deposit_funds", "submit_information_request", "reauthorize_payout_methods", "update_payout_profile", "card_usage_review", "verify_identity", "sign_formation_documents", "connect_fulfillment_tracker", "setup_apple_pay_domains", "configure_tax_remitter", "add_vat_registration" ], "example": "verify_identity", "type": "string" }, "blocked_capabilities": { "items": { "description": "Capabilities gated until this is resolved", "example": "standard_payout", "type": "string" }, "type": "array" }, "cta": { "description": "The URL the call-to-action links to, or null when there is no button", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/", "type": [ "string", "null" ] }, "cta_label": { "description": "Button label, or empty when there is no button", "example": "Verify now", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Complete verification to withdraw your earnings.", "type": "string" }, "icon_url": { "description": "The URL of the action's illustration icon, or null if it has none", "example": "https://whop.com/illustrations/orange/shield.svg", "type": [ "string", "null" ] }, "status": { "description": "required (act now) or pending (under review)", "enum": [ "required", "pending" ], "example": "required", "type": "string" }, "title": { "description": "Headline for the action", "example": "Complete your identity verification", "type": "string" } }, "required": [ "action", "status", "title", "description", "cta_label", "cta", "icon_url", "blocked_capabilities" ], "type": "object" }, "AccountReserve": { "properties": { "amount": { "description": "Total held in this currency, in native units, as a decimal string. `usd` and `usdt` are reported as one `usd` entry, matching how the balance row groups them.", "example": "125.5", "type": "string" }, "by_type": { "items": { "$ref": "#/components/schemas/AccountReserveType", "description": "The total split by why each part is held. Only reasons holding a non-zero amount appear, so these can sum to less than `amount`, never more." }, "type": "array" }, "currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`.", "example": "usd", "type": "string" }, "unlocks_by_date": { "items": { "$ref": "#/components/schemas/AccountReserveUnlock", "description": "When the held money unlocks, one entry per day, earliest first. Money whose release depends on something other than a date is left out, so these can sum to less than `amount`, never more." }, "type": "array" } }, "required": [ "currency", "amount", "by_type", "unlocks_by_date" ], "type": "object" }, "AccountReserveControl": { "properties": { "hold_period_days": { "description": "Number of days reserved funds are held before release.", "example": 14, "type": "integer" }, "percentage": { "description": "Percentage of incoming payment volume held in reserve. `null` when no reserve is applied.", "example": 15.0, "type": [ "number", "null" ] } }, "required": [ "percentage", "hold_period_days" ], "type": "object" }, "AccountReserveType": { "properties": { "amount": { "description": "Amount held for this reason, in native units, as a decimal string.", "example": "100.0", "type": "string" }, "hold_period_days": { "description": "Days money is currently held for this reason before it unlocks, or `null` when release depends on something other than time. Money already held keeps the terms it was taken under.", "example": 90, "type": [ "integer", "null" ] }, "percentage": { "description": "Percentage of each incoming payment currently held for this reason, or `null` when the reason is not a percentage of anything. Money already held keeps the release date it was given, which `unlocks_by_date` reflects.", "example": 25.0, "type": [ "number", "null" ] }, "type": { "description": "Why this part of the balance is held. `regular` is the account's standing risk reserve; `bnpl` and `sequra` cover buy-now-pay-later settlement; `preshipment_hold` covers a physical order that has not shipped yet; `fraud_hold` is held while activity is reviewed.", "enum": [ "regular", "bnpl", "sequra", "fraud_hold", "preshipment_hold" ], "example": "regular", "type": "string" } }, "required": [ "type", "amount", "percentage", "hold_period_days" ], "type": "object" }, "AccountReserveUnlock": { "properties": { "amount": { "description": "Amount unlocking that day across every reason, in native units, as a decimal string.", "example": "100.0", "type": "string" }, "date": { "description": "The day this money unlocks, as an ISO 8601 date.", "example": "2026-01-01", "type": "string" } }, "required": [ "date", "amount" ], "type": "object" }, "AccountResolutionCenterAutoRefundControl": { "properties": { "card_threshold_usd": { "description": "Maximum card-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for cards.", "example": 50, "type": [ "number", "null" ] }, "financing_threshold_usd": { "description": "Maximum financing-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for financing.", "example": 25, "type": [ "number", "null" ] }, "locked": { "description": "Whether the account owner is prevented from changing these thresholds.", "example": false, "type": "boolean" }, "paypal_threshold_usd": { "description": "Maximum PayPal-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for PayPal.", "example": 40, "type": [ "number", "null" ] } }, "required": [ "card_threshold_usd", "financing_threshold_usd", "paypal_threshold_usd", "locked" ], "type": "object" }, "AccountSocialLink": { "properties": { "id": { "description": "The ID of the social link", "example": "social_1", "type": "string" }, "title": { "description": "The optional display title for the social link", "example": "@shinetimedetail", "type": [ "string", "null" ] }, "url": { "description": "The social link URL", "example": "https://instagram.com/shinetimedetail", "type": "string" }, "website": { "description": "The social platform for this link", "enum": [ "x", "instagram", "facebook", "tiktok", "youtube", "linkedin", "twitch", "website", "custom" ], "example": "instagram", "type": "string" } }, "required": [ "id", "website", "url", "title" ], "type": "object" }, "AccountStorePageConfig": { "properties": { "accent_color": { "description": "Accent color used on the account store page.", "enum": [ "ruby", "tomato", "red", "crimson", "pink", "plum", "purple", "violet", "iris", "cyan", "teal", "jade", "green", "grass", "brown", "blue", "orange", "indigo", "sky", "mint", "yellow", "amber", "lime", "lemon", "magenta", "gold", "bronze", "gray", null ], "example": "red", "type": [ "string", "null" ] }, "layout": { "description": "Layout used on the account store page.", "enum": [ "featured", "compact", null ], "example": "compact", "type": [ "string", "null" ] }, "profile_variant": { "description": "Profile presentation used on the account store page.", "enum": [ "personal", "business", null ], "example": "business", "type": [ "string", "null" ] }, "whop_affiliate_link": { "description": "Whether the account store page shows a Whop affiliate link.", "example": true, "type": "boolean" } }, "required": [ "accent_color", "layout", "profile_variant", "whop_affiliate_link" ], "type": "object" }, "AccountSummary": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "AccountTaxIdentifier": { "properties": { "id": { "description": "Tax identifier ID.", "example": "txid_xxxxxxxxxxxxxx", "type": "string" }, "tax_id_type": { "description": "Tax ID type.", "enum": [ "ad_nrt", "ao_tin", "ar_cuit", "al_tin", "am_tin", "aw_tin", "au_abn", "au_arn", "eu_vat", "az_tin", "bs_tin", "bh_vat", "bd_bin", "bb_tin", "by_tin", "bj_ifu", "bo_tin", "ba_tin", "br_cnpj", "br_cpf", "bg_uic", "bf_ifu", "kh_tin", "cm_niu", "ca_bn", "ca_gst_hst", "ca_pst_bc", "ca_pst_mb", "ca_pst_sk", "ca_qst", "cv_nif", "cl_tin", "cn_tin", "co_nit", "cd_nif", "cr_tin", "hr_oib", "do_rcn", "ec_ruc", "eg_tin", "sv_nit", "et_tin", "eu_oss_vat", "ge_vat", "gh_tin", "de_stn", "gb_vat", "gn_nif", "hk_br", "hu_tin", "is_vat", "in_gst", "id_npwp", "il_vat", "jp_cn", "jp_rn", "jp_trn", "kz_bin", "ke_pin", "kg_tin", "la_tin", "li_uid", "li_vat", "my_frp", "my_itn", "my_sst", "mr_nif", "mx_rfc", "md_vat", "me_pib", "ma_vat", "np_pan", "nz_gst", "ng_tin", "mk_vat", "no_vat", "no_voec", "om_vat", "pe_ruc", "ph_tin", "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" ], "example": "eu_vat", "type": "string" }, "tax_id_value": { "description": "Tax ID value.", "example": "DE123456789", "type": "string" } }, "required": [ "id", "tax_id_type", "tax_id_value" ], "type": "object" }, "AccountWallet": { "properties": { "address": { "description": "The on-chain address of the wallet", "example": "0xabc123", "type": "string" }, "id": { "description": "Wallet ID, prefixed `wallet_`.", "example": "cwal_xxxxxxxxxxxxxx", "type": "string" }, "network": { "description": "The blockchain network the wallet lives on", "enum": [ "solana", "ethereum", "bitcoin" ], "example": "ethereum", "type": "string" } }, "required": [ "id", "address", "network" ], "type": "object" }, "AccountWithdrawalScheduleControl": { "properties": { "day": { "description": "Day the automatic withdrawal runs on: 0-6 (Sunday-Saturday) for `weekly`, 1-31 for `monthly`. `null` for `manual` and `daily`.", "type": [ "integer", "null" ] }, "frequency": { "description": "How often the account's balance automatically withdraws.", "enum": [ "manual", "daily", "weekly", "monthly" ], "example": "manual", "type": "string" }, "next_payout_date": { "description": "Next date the automatic withdrawal is scheduled to run, as an ISO 8601 date. `null` for `manual` and `daily`, where no single next date applies.", "type": [ "string", "null" ] } }, "required": [ "frequency", "day", "next_payout_date" ], "type": "object" }, "Ad": { "properties": { "ad_campaign": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad campaign this ad belongs to." }, "ad_group": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad group this ad belongs to." }, "added_to_cart_value": { "description": "USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1850.0, "type": "number" }, "added_to_carts": { "description": "Whop pixel-attributed add-to-cart events, last-click.", "example": 74, "type": "number" }, "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "learn_more", "shop_now", "sign_up", "subscribe", "get_started", "book_now", "apply_now", "contact_us", "download", "order_now", "buy_now", "get_quote", "message_page", "whatsapp_message", "instagram_message", "call_now", "get_directions", "send_updates", "get_offer", "watch_more", "listen_now", "play_game", "open_link", "no_button", "get_offer_view", "get_event_tickets", "see_menu", "request_time", "event_rsvp", "see_details", "view_instagram_profile", null ], "example": "learn_more", "type": [ "string", "null" ] }, "click_through_rate": { "description": "Clicks divided by impressions, between 0 and 1.", "example": 0.0261, "type": "number" }, "clicks": { "description": "The number of clicks.", "example": 1337, "type": "number" }, "completed_registration_value": { "description": "USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 95.0, "type": "number" }, "completed_registrations": { "description": "Whop pixel-attributed complete-registration events, last-click.", "example": 19, "type": "number" }, "contact_value": { "description": "USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 175.0, "type": "number" }, "contacts": { "description": "Whop pixel-attributed contact events, last-click.", "example": 27, "type": "number" }, "cost_per_added_to_cart": { "description": "Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.", "example": 6.515675675675676, "type": [ "number", "null" ] }, "cost_per_click": { "description": "Spend divided by clicks; 0 when there are no clicks.", "example": 0.36, "type": "number" }, "cost_per_completed_registration": { "description": "Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.", "example": 25.37684210526316, "type": [ "number", "null" ] }, "cost_per_contact": { "description": "Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.", "example": 17.85777777777778, "type": [ "number", "null" ] }, "cost_per_lead": { "description": "Spend divided by attributed leads; null when leads are not a goal and none are attributed.", "example": 3.984793388429752, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 9.42, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 12.68842105263158, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.", "example": 7.653333333333333, "type": [ "number", "null" ] }, "cost_per_schedule": { "description": "Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.", "example": 10.48173913043478, "type": [ "number", "null" ] }, "cost_per_submitted_application": { "description": "Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.", "example": 40.18, "type": [ "number", "null" ] }, "cost_per_unique_click": { "description": "Spend divided by unique clicks; null when there are no unique clicks.", "example": 0.48, "type": [ "number", "null" ] }, "cost_per_viewed_content": { "description": "Spend divided by attributed view-content events; null when they are not the goal and none are attributed.", "example": 0.2253084112149533, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "creatives": { "items": { "$ref": "#/components/schemas/AdCreative", "description": "The creative assets used by this ad. The original asset has a null format; square, vertical, and horizontal entries are placement-specific variants. A carousel ad returns one format-null entry per attachment, in order." }, "type": "array" }, "custom_conversions": { "description": "Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.", "example": 63, "type": "number" }, "custom_event_counts": { "description": "Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.", "example": { "booked_detail": 63 }, "type": "object" }, "custom_event_values": { "description": "Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.", "example": { "booked_detail": 4820.0 }, "type": "object" }, "delivery_status": { "description": "Whether the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "rejected", "in_review", "draft", "campaign_paused", "ad_group_paused", "paused", "processing", "issues", "scheduled", "learning_limited", "learning", "active" ], "example": "paused", "type": "string" }, "descriptions": { "items": { "description": "The description variants shown on the ad.", "example": "Paint correction included", "type": "string" }, "type": "array" }, "existing_post_id": { "description": "The post you pointed this ad at, when it promotes one you already published — a Facebook post, Instagram media, or TikTok video ID. `null` when the ad uses uploaded creatives.", "example": "xxxxxxxxxxxxxxxx_98765", "type": [ "string", "null" ] }, "frequency": { "description": "Platform-reported impressions divided by reach.", "type": [ "number", "null" ] }, "headlines": { "items": { "description": "The headline variants shown on the ad.", "example": "Austin's mobile detailers", "type": "string" }, "type": "array" }, "id": { "description": "Unique identifier for the ad, prefixed `ad_`.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "The number of impressions.", "example": 51204, "type": "number" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting this ad. Empty when there are none." }, "type": "array" }, "lead_form": { "description": "The instant lead form shown when someone taps this ad. `null` when the ad group's conversion_location is not an instant-form destination.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadForm" }, { "type": "null" } ] }, "lead_form_id": { "description": "The ad platform's ID for the instant form the ad uses. Set when the ad references an existing form via `lead_form_id`, or once a form built from `lead_form` has been created on the platform.", "example": "1037724182084885", "type": [ "string", "null" ] }, "lead_value": { "description": "USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1180.0, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 121, "type": "number" }, "link_clicks": { "description": "Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.", "example": 1071, "type": "number" }, "messaging_config": { "description": "Welcome message for click-to-message ads, shown when the conversation opens. `null` when the ad has none.", "oneOf": [ { "$ref": "#/components/schemas/AdMessagingConfig" }, { "type": "null" } ] }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": true, "type": "boolean" }, "post_id": { "description": "The post the ad network serves for this ad, as `pageID_postID` on Meta — the post Meta created for an uploaded creative, or the post being promoted. Use it to open the live post, or to promote the same post from another ad. `null` until the network has created the post.", "example": "xxxxxxxxxxxxxxxx_98765", "type": [ "string", "null" ] }, "post_source": { "description": "Identifies the network that owns `existing_post_id`; `null` when the ad uses uploaded creatives.", "enum": [ "facebook", "instagram", null ], "example": "facebook", "type": [ "string", "null" ] }, "post_thumbnail_url": { "description": "Preview image of the post named by `existing_post_id`. `null` for ads that use uploaded creatives, or until the post's media has been fetched from the network.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "primary_texts": { "items": { "description": "The primary text variants shown in the ad body.", "example": "Book a two-day ceramic coating and keep the shine for three years.", "type": "string" }, "type": "array" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 9462.0, "type": "number" }, "purchases": { "description": "Whop pixel-attributed purchases, last-click.", "example": 38, "type": "number" }, "reach": { "description": "The number of unique people who saw this.", "example": 0, "type": "number" }, "result_event": { "description": "The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.", "enum": [ "purchase", "lead", "schedule", "submit_application", "contact", "complete_registration", "view_content", "add_to_cart", "custom", "messaging_conversation", null ], "example": "custom", "type": [ "string", "null" ] }, "result_event_name": { "description": "The merchant-defined event name when result_event is custom; null for the standard events.", "example": "booked_detail", "type": [ "string", "null" ] }, "results": { "description": "The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.", "example": 63, "type": [ "number", "null" ] }, "return_on_ad_spend": { "description": "Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.", "example": 19.62419113987058, "type": "number" }, "schedule_value": { "description": "USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 640.0, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 46, "type": "number" }, "social_accounts": { "items": { "$ref": "#/components/schemas/AdEntityReference", "description": "The social accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed `sacc_`." }, "type": "array" }, "spend": { "description": "The amount charged, in spend_currency.", "example": 482.16, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "status": { "description": "Whether the ad is enabled. `active` and `paused` are set by you; `in_review` and `rejected` come from ad review.", "enum": [ "active", "paused", "in_review", "rejected" ], "example": "paused", "type": "string" }, "submitted_application_value": { "description": "USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 300.0, "type": "number" }, "submitted_applications": { "description": "Whop pixel-attributed submit-application events, last-click.", "example": 12, "type": "number" }, "title": { "description": "Display title of the ad.", "example": "Ceramic coating — new ad group", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "type": [ "number", "null" ] }, "unique_clicks": { "description": "People who clicked, reported by the Whop pixel, counted once per person.", "example": 1012, "type": "number" }, "updated_at": { "description": "When the ad was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "url": { "description": "The URL the ad links to, without its query string. Parameters belong in `url_parameters`; any you send on `url` are moved there.", "example": "https://shinetime.example/ceramic-coating", "type": [ "string", "null" ] }, "url_parameters": { "description": "Every query parameter appended to the URL, keyed by parameter name — including any you sent on `url` itself. Whop adds its own click-attribution parameters on top; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": {}, "type": "object" }, "viewed_content_value": { "description": "USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 0.0, "type": "number" }, "viewed_contents": { "description": "Whop pixel-attributed view-content events, last-click.", "example": 2140, "type": "number" } }, "required": [ "click_through_rate", "clicks", "cost_per_click", "cost_per_unique_click", "cost_per_lead", "cost_per_mille", "cost_per_purchase", "cost_per_schedule", "cost_per_submitted_application", "cost_per_contact", "cost_per_completed_registration", "cost_per_viewed_content", "cost_per_added_to_cart", "cost_per_result", "frequency", "impressions", "leads", "link_clicks", "purchase_value", "purchases", "reach", "result_event", "result_event_name", "results", "return_on_ad_spend", "spend", "spend_currency", "unique_click_through_rate", "unique_clicks", "schedules", "submitted_applications", "contacts", "completed_registrations", "viewed_contents", "added_to_carts", "custom_conversions", "custom_event_counts", "custom_event_values", "lead_value", "schedule_value", "submitted_application_value", "contact_value", "completed_registration_value", "viewed_content_value", "added_to_cart_value", "id", "title", "status", "delivery_status", "primary_texts", "headlines", "descriptions", "call_to_action", "url", "url_parameters", "post_id", "existing_post_id", "post_source", "post_thumbnail_url", "ad_group", "ad_campaign", "creatives", "social_accounts", "created_at", "updated_at", "issues" ], "type": "object" }, "AdCampaign": { "properties": { "added_to_cart_value": { "description": "USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 12650.0, "type": "number" }, "added_to_carts": { "description": "Whop pixel-attributed add-to-cart events, last-click.", "example": 165, "type": "number" }, "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, and `maximum_target` never bids above a cap.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "The campaign's budget, in the ad account's currency. `null` when each ad group sets its own budget instead.", "example": 50.0, "type": [ "number", "null" ] }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`).", "enum": [ "ad_campaign", "ad_group", null ], "example": "ad_group", "type": [ "string", "null" ] }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`).", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "click_through_rate": { "description": "Clicks divided by impressions, between 0 and 1.", "example": 0.025, "type": "number" }, "clicks": { "description": "The number of clicks.", "example": 5500, "type": "number" }, "completed_registration_value": { "description": "USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1650.0, "type": "number" }, "completed_registrations": { "description": "Whop pixel-attributed complete-registration events, last-click.", "example": 55, "type": "number" }, "contact_value": { "description": "USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 2640.0, "type": "number" }, "contacts": { "description": "Whop pixel-attributed contact events, last-click.", "example": 88, "type": "number" }, "cost_per_added_to_cart": { "description": "Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.", "example": 8.0, "type": [ "number", "null" ] }, "cost_per_click": { "description": "Spend divided by clicks; 0 when there are no clicks.", "example": 0.24, "type": "number" }, "cost_per_completed_registration": { "description": "Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.", "example": 24.0, "type": [ "number", "null" ] }, "cost_per_contact": { "description": "Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.", "example": 15.0, "type": [ "number", "null" ] }, "cost_per_lead": { "description": "Spend divided by attributed leads; null when leads are not a goal and none are attributed.", "example": 10.0, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 6.0, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 30.0, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.", "example": 40.0, "type": [ "number", "null" ] }, "cost_per_schedule": { "description": "Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.", "example": 22.0, "type": [ "number", "null" ] }, "cost_per_submitted_application": { "description": "Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.", "example": 120.0, "type": [ "number", "null" ] }, "cost_per_unique_click": { "description": "Spend divided by unique clicks; null when there are no unique clicks.", "example": 0.4, "type": [ "number", "null" ] }, "cost_per_viewed_content": { "description": "Spend divided by attributed view-content events; null when they are not the goal and none are attributed.", "example": 1.1, "type": [ "number", "null" ] }, "created_at": { "description": "When the campaign was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_conversions": { "description": "Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.", "example": 41, "type": "number" }, "custom_event_counts": { "description": "Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.", "example": { "gift_card_purchased": 5, "quote_requested": 33 }, "type": "object" }, "custom_event_values": { "description": "Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.", "example": { "gift_card_purchased": 750.0, "quote_requested": 0.0 }, "type": "object" }, "delivery_status": { "description": "Whether the campaign's ads are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "frequency": { "description": "Platform-reported impressions divided by reach.", "type": [ "number", "null" ] }, "id": { "description": "Unique identifier for the ad campaign, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "The number of impressions.", "example": 220000, "type": "number" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting the campaign and its descendant ad groups and ads." }, "type": "array" }, "lead_value": { "description": "USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 3960.0, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 132, "type": "number" }, "link_clicks": { "description": "Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.", "example": 4400, "type": "number" }, "objective": { "description": "The goal the campaign optimizes toward.", "enum": [ "awareness", "traffic", "engagement", "leads", "sales", null ], "example": "leads", "type": [ "string", "null" ] }, "optimization_goal": { "description": "The event the campaign optimizes for when a single goal is set campaign-wide. `null` when each ad group sets its own optimization_goal.", "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok" ], "example": "meta", "type": "string" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 7920.0, "type": "number" }, "purchases": { "description": "Whop pixel-attributed purchases, last-click.", "example": 44, "type": "number" }, "reach": { "description": "The number of unique people who saw this.", "example": 0, "type": "number" }, "result_event": { "description": "The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.", "enum": [ "purchase", "lead", "schedule", "submit_application", "contact", "complete_registration", "view_content", "add_to_cart", "custom", "messaging_conversation", null ], "example": "custom", "type": [ "string", "null" ] }, "result_event_name": { "description": "The merchant-defined event name when result_event is custom; null for the standard events.", "example": "quote_requested", "type": [ "string", "null" ] }, "results": { "description": "The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.", "example": 33, "type": [ "number", "null" ] }, "return_on_ad_spend": { "description": "Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.", "example": 6.0, "type": "number" }, "schedule_value": { "description": "USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 5400.0, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 60, "type": "number" }, "special_ad_categories": { "items": { "description": "Regulated categories the campaign is declared under. Ads in these categories are subject to extra targeting restrictions. Empty when none apply.", "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "spend": { "description": "The amount charged, in spend_currency.", "example": 1320.0, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "status": { "description": "The lifecycle status of the ad campaign.", "enum": [ "active", "paused", "inactive", "stale", "pending_refund", "payment_failed", "draft", "in_review", "flagged", "importing", "imported", "duplicating" ], "example": "active", "type": "string" }, "submitted_application_value": { "description": "USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1320.0, "type": "number" }, "submitted_applications": { "description": "Whop pixel-attributed submit-application events, last-click.", "example": 11, "type": "number" }, "title": { "description": "Display name of the ad campaign.", "example": "Ceramic coating — Austin leads", "type": "string" }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "type": [ "number", "null" ] }, "unique_clicks": { "description": "People who clicked, reported by the Whop pixel, counted once per person.", "example": 3300, "type": "number" }, "updated_at": { "description": "When the campaign was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewed_content_value": { "description": "USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 8400.0, "type": "number" }, "viewed_contents": { "description": "Whop pixel-attributed view-content events, last-click.", "example": 1200, "type": "number" } }, "required": [ "click_through_rate", "clicks", "cost_per_click", "cost_per_unique_click", "cost_per_lead", "cost_per_mille", "cost_per_purchase", "cost_per_schedule", "cost_per_submitted_application", "cost_per_contact", "cost_per_completed_registration", "cost_per_viewed_content", "cost_per_added_to_cart", "cost_per_result", "frequency", "impressions", "leads", "link_clicks", "purchase_value", "purchases", "reach", "result_event", "result_event_name", "results", "return_on_ad_spend", "spend", "spend_currency", "unique_click_through_rate", "unique_clicks", "schedules", "submitted_applications", "contacts", "completed_registrations", "viewed_contents", "added_to_carts", "custom_conversions", "custom_event_counts", "custom_event_values", "lead_value", "schedule_value", "submitted_application_value", "contact_value", "completed_registration_value", "viewed_content_value", "added_to_cart_value", "id", "title", "status", "delivery_status", "platform", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "budget_type", "budget_optimization", "created_at", "updated_at", "issues" ], "type": "object" }, "AdCreative": { "properties": { "crop": { "description": "The saved crop window for this creative, in source image pixels. Null for the original asset or a format that has not been cropped.", "oneOf": [ { "$ref": "#/components/schemas/AdCreativeCrop" }, { "type": "null" } ] }, "format": { "description": "The placement variant this asset covers, or null for the original asset.", "enum": [ "square", "vertical", "horizontal", null ], "example": "vertical", "type": [ "string", "null" ] }, "id": { "description": "The creative attachment's file id.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "media_type": { "description": "The kind of asset, image or video.", "example": "image", "type": [ "string", "null" ] }, "url": { "description": "CDN url of the asset.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "format", "url", "media_type", "crop" ], "type": "object" }, "AdCreativeCrop": { "properties": { "height": { "description": "Height of the crop window in source pixels.", "example": 1000, "type": "number" }, "width": { "description": "Width of the crop window in source pixels.", "example": 1000, "type": "number" }, "x": { "description": "Left edge of the crop window in source pixels.", "example": 40, "type": "number" }, "y": { "description": "Top edge of the crop window in source pixels.", "example": 0, "type": "number" } }, "required": [ "x", "y", "width", "height" ], "type": "object" }, "AdEntityReference": { "properties": { "id": { "description": "The referenced entity's id.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "AdGroup": { "properties": { "ad_campaign": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad campaign this ad group belongs to." }, "added_to_cart_value": { "description": "USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 12650.0, "type": "number" }, "added_to_carts": { "description": "Whop pixel-attributed add-to-cart events, last-click.", "example": 165, "type": "number" }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiences", "description": "Saved audiences this ad group delivers to or excludes." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "This ad group's budget, in the ad account's currency. `null` when the budget is set on the campaign instead.", "example": 60.0, "type": [ "number", "null" ] }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`).", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "click_through_rate": { "description": "Clicks divided by impressions, between 0 and 1.", "example": 0.025, "type": "number" }, "clicks": { "description": "The number of clicks.", "example": 5500, "type": "number" }, "completed_registration_value": { "description": "USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1650.0, "type": "number" }, "completed_registrations": { "description": "Whop pixel-attributed complete-registration events, last-click.", "example": 55, "type": "number" }, "contact_value": { "description": "USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 2640.0, "type": "number" }, "contacts": { "description": "Whop pixel-attributed contact events, last-click.", "example": 88, "type": "number" }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms", null ], "example": "website", "type": [ "string", "null" ] }, "cost_per_added_to_cart": { "description": "Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.", "example": 8.0, "type": [ "number", "null" ] }, "cost_per_click": { "description": "Spend divided by clicks; 0 when there are no clicks.", "example": 0.24, "type": "number" }, "cost_per_completed_registration": { "description": "Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.", "example": 24.0, "type": [ "number", "null" ] }, "cost_per_contact": { "description": "Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.", "example": 15.0, "type": [ "number", "null" ] }, "cost_per_lead": { "description": "Spend divided by attributed leads; null when leads are not a goal and none are attributed.", "example": 10.0, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 6.0, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 30.0, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.", "example": 40.0, "type": [ "number", "null" ] }, "cost_per_schedule": { "description": "Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.", "example": 22.0, "type": [ "number", "null" ] }, "cost_per_submitted_application": { "description": "Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.", "example": 120.0, "type": [ "number", "null" ] }, "cost_per_unique_click": { "description": "Spend divided by unique clicks; null when there are no unique clicks.", "example": 0.4, "type": [ "number", "null" ] }, "cost_per_viewed_content": { "description": "Spend divided by attributed view-content events; null when they are not the goal and none are attributed.", "example": 1.1, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad group was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_conversions": { "description": "Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.", "example": 41, "type": "number" }, "custom_event_counts": { "description": "Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.", "example": { "gift_card_purchased": 5, "quote_requested": 33 }, "type": "object" }, "custom_event_values": { "description": "Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.", "example": { "gift_card_purchased": 750.0, "quote_requested": 0.0 }, "type": "object" }, "delivery_status": { "description": "Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "all_ads_rejected", "rejected", "draft", "no_ads", "campaign_paused", "paused", "processing", "issues", "scheduled", "completed", "ads_off", "learning_limited", "learning", "active" ], "example": "no_ads", "type": "string" }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographics", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). `null` for `minimum_cost` bidding.", "example": 40.0, "type": [ "number", "null" ] }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargeting", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. Can't be combined with automatic audience targeting. Special ad category campaigns are limited to approved interests." }, "devices": { "$ref": "#/components/schemas/AdGroupDevices", "description": "Device platforms and operating systems targeted." }, "dynamic_creative": { "description": "Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations.", "example": false, "type": "boolean" }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. `null` when it runs until paused.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "frequency": { "description": "Platform-reported impressions divided by reach.", "type": [ "number", "null" ] }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective; `null` when uncapped.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupFrequencyCap" }, { "type": "null" } ] }, "id": { "description": "Unique identifier for the ad group, prefixed `adgrp_`.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "The number of impressions.", "example": 220000, "type": "number" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting this ad group and its ads. Empty when there are none." }, "type": "array" }, "languages": { "items": { "description": "Languages targeted, as ISO 639 codes such as `en` or `es`. A region-specific locale with no ISO code appears as its numeric platform locale key. Empty targets all languages.", "example": "en", "type": "string" }, "type": "array" }, "lead_value": { "description": "USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 3960.0, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 132, "type": "number" }, "link_clicks": { "description": "Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.", "example": 4400, "type": "number" }, "message_apps": { "items": { "description": "Apps the conversation opens in when `conversion_location` is `messaging`. Empty for other conversion locations.", "enum": [ "messenger", "instagram", "whatsapp" ], "example": "instagram", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day. `null` when no floor is set.", "example": 25.0, "type": [ "number", "null" ] }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement", null ], "example": "conversions", "type": [ "string", "null" ] }, "placements": { "items": { "$ref": "#/components/schemas/AdGroupPlacement", "description": "Where ads can appear, per platform. Empty when placements are chosen automatically." }, "type": "array" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 7920.0, "type": "number" }, "purchases": { "description": "Whop pixel-attributed purchases, last-click.", "example": 44, "type": "number" }, "reach": { "description": "The number of unique people who saw this.", "example": 0, "type": "number" }, "regions": { "$ref": "#/components/schemas/AdGroupRegions", "description": "Locations targeted and excluded." }, "result_event": { "description": "The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.", "enum": [ "purchase", "lead", "schedule", "submit_application", "contact", "complete_registration", "view_content", "add_to_cart", "custom", "messaging_conversation", null ], "example": "custom", "type": [ "string", "null" ] }, "result_event_name": { "description": "The merchant-defined event name when result_event is custom; null for the standard events.", "example": "quote_requested", "type": [ "string", "null" ] }, "results": { "description": "The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.", "example": 33, "type": [ "number", "null" ] }, "return_on_ad_spend": { "description": "Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.", "example": 6.0, "type": "number" }, "schedule_value": { "description": "USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 5400.0, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 60, "type": "number" }, "spend": { "description": "The amount charged, in spend_currency.", "example": 1320.0, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. `null` when it starts as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Whether the ad group is enabled. `active` and `paused` are set by you; `rejected` means it failed ad review; `duplicating` is a copy still being filled in.", "enum": [ "active", "paused", "rejected", "duplicating" ], "example": "active", "type": "string" }, "submitted_application_value": { "description": "USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1320.0, "type": "number" }, "submitted_applications": { "description": "Whop pixel-attributed submit-application events, last-click.", "example": 11, "type": "number" }, "title": { "description": "Display name of the ad group.", "example": "Austin ceramic coating — repeat customers", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "type": [ "number", "null" ] }, "unique_clicks": { "description": "People who clicked, reported by the Whop pixel, counted once per person.", "example": 3300, "type": "number" }, "updated_at": { "description": "When the ad group was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewed_content_value": { "description": "USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 8400.0, "type": "number" }, "viewed_contents": { "description": "Whop pixel-attributed view-content events, last-click.", "example": 1200, "type": "number" } }, "required": [ "click_through_rate", "clicks", "cost_per_click", "cost_per_unique_click", "cost_per_lead", "cost_per_mille", "cost_per_purchase", "cost_per_schedule", "cost_per_submitted_application", "cost_per_contact", "cost_per_completed_registration", "cost_per_viewed_content", "cost_per_added_to_cart", "cost_per_result", "frequency", "impressions", "leads", "link_clicks", "purchase_value", "purchases", "reach", "result_event", "result_event_name", "results", "return_on_ad_spend", "spend", "spend_currency", "unique_click_through_rate", "unique_clicks", "schedules", "submitted_applications", "contacts", "completed_registrations", "viewed_contents", "added_to_carts", "custom_conversions", "custom_event_counts", "custom_event_values", "lead_value", "schedule_value", "submitted_application_value", "contact_value", "completed_registration_value", "viewed_content_value", "added_to_cart_value", "id", "title", "status", "delivery_status", "optimization_goal", "conversion_event", "budget_amount", "budget_type", "bid_type", "desired_cost_per_result", "starts_at", "ends_at", "regions", "demographics", "detailed_targeting", "audiences", "languages", "devices", "frequency_cap", "placements", "ad_campaign", "created_at", "updated_at", "issues" ], "type": "object" }, "AdGroupAudiences": { "properties": { "exclude": { "items": { "description": "IDs of saved audiences excluded from delivery, prefixed `adaud_`.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "include": { "items": { "description": "IDs of saved audiences the ad group delivers to, prefixed `adaud_`.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "include", "exclude" ], "type": "object" }, "AdGroupAudiencesBody": { "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic.", "properties": { "exclude": { "description": "IDs of saved audiences to exclude from delivery, prefixed `adaud_`.", "items": { "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "include": { "description": "IDs of saved audiences to deliver to, prefixed `adaud_`.", "items": { "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "title": "Audiences", "type": "object" }, "AdGroupBehaviorCategory": { "properties": { "behavior_type": { "description": "On ad platforms that scope behavior categories, what this one is measured on. Send back the value the targeting_options endpoint returned alongside the id. Absent on platforms that don't scope them.", "enum": [ "video", "creator", "hashtag" ], "example": "video", "type": "string" }, "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6007101291578", "type": "string" }, "name": { "description": "Category name, such as `Frequent travelers`.", "example": "Recent vehicle purchase (30 days)", "type": "string" }, "period": { "description": "On ad platforms that scope behavior categories, how many days of activity the category covers. Absent on platforms that don't scope them.", "type": "number" } }, "required": [ "id" ], "type": "object" }, "AdGroupCity": { "properties": { "key": { "description": "The ad platform's key for the city in its location taxonomy.", "example": "2418046", "type": "string" }, "name": { "description": "City name, such as `Austin`. Absent when the platform doesn't return one.", "example": "Austin", "type": "string" } }, "required": [ "key" ], "type": "object" }, "AdGroupCustomLocation": { "properties": { "distance_unit": { "description": "Unit for `radius`.", "enum": [ "mile", "kilometer" ], "example": "mile", "type": "string" }, "latitude": { "description": "Latitude of the center point.", "example": 30.2672, "type": "number" }, "longitude": { "description": "Longitude of the center point.", "example": -97.7431, "type": "number" }, "name": { "description": "Label for the location, such as a city or address. Absent when the location has no label.", "example": "4180 Burnet Rd, Austin TX 78756", "type": "string" }, "radius": { "description": "Radius around the center point, in `distance_unit`.", "example": 25.0, "type": "number" } }, "required": [ "latitude", "longitude", "radius", "distance_unit" ], "type": "object" }, "AdGroupDemographicCategory": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6002714398172", "type": "string" }, "name": { "description": "Category name, such as `Recently moved`.", "example": "Recently moved", "type": "string" }, "type": { "description": "Kind of demographic the category belongs to.", "enum": [ "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors" ], "example": "life_events", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "AdGroupDemographics": { "properties": { "automatic": { "description": "Whether automatic audience targeting is on (Advantage+ on Meta). When `true`, the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.", "example": false, "type": "boolean" }, "gender": { "description": "Gender targeted.", "enum": [ "all", "male", "female" ], "example": "all", "type": "string" }, "maximum_age": { "description": "Oldest age targeted. `null` when no maximum is set.", "example": 64, "type": [ "number", "null" ] }, "minimum_age": { "description": "Youngest age targeted. `null` when no minimum is set.", "example": 21, "type": [ "number", "null" ] } }, "required": [ "automatic", "minimum_age", "maximum_age", "gender" ], "type": "object" }, "AdGroupDemographicsBody": { "description": "Age, gender, and automatic-audience targeting.", "properties": { "automatic": { "description": "Turn on automatic audience targeting (Advantage+ on Meta): the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.", "example": false, "type": "boolean" }, "gender": { "description": "Gender to target.", "enum": [ "all", "male", "female" ], "example": "all", "type": "string" }, "maximum_age": { "description": "Oldest age to target.", "example": 64, "type": "integer" }, "minimum_age": { "description": "Youngest age to target.", "example": 21, "type": "integer" } }, "title": "Demographics", "type": "object" }, "AdGroupDetailedTargeting": { "properties": { "behaviors": { "items": { "$ref": "#/components/schemas/AdGroupBehaviorCategory", "description": "Behavior categories targeted, such as frequent travelers." }, "type": "array" }, "demographics": { "items": { "$ref": "#/components/schemas/AdGroupDemographicCategory", "description": "Demographic categories targeted, such as life events, industries, work employers, job titles, schools, or majors. OR'd with interests and behaviors." }, "type": "array" }, "interests": { "items": { "$ref": "#/components/schemas/AdGroupTargetingCategory", "description": "Interest categories targeted, such as an interest in movies." }, "type": "array" } }, "required": [ "interests", "behaviors", "demographics" ], "type": "object" }, "AdGroupDetailedTargetingBody": { "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories.", "properties": { "behaviors": { "description": "Behavior categories to target, such as frequent travelers.", "items": { "properties": { "behavior_type": { "description": "On ad platforms that scope behavior categories, what this one is measured on. Send back the value the targeting_options endpoint returned alongside the id.", "enum": [ "video", "creator", "hashtag" ], "example": "video", "type": "string" }, "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6007101291578", "type": "string" }, "name": { "description": "Category name, such as `Frequent travelers`.", "example": "Recent vehicle purchase (30 days)", "type": "string" }, "period": { "description": "On ad platforms that scope behavior categories, how many days of activity the category covers.", "type": "integer" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "demographics": { "description": "Demographic categories to target, such as life events, industries, work employers, job titles, schools, or majors.", "items": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6002714398172", "type": "string" }, "name": { "description": "Category name, such as `Recently moved`.", "example": "Recently moved", "type": "string" }, "type": { "description": "Kind of demographic the category belongs to.", "enum": [ "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors" ], "example": "life_events", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "type": "array" }, "interests": { "description": "Interest categories to target, such as an interest in movies.", "items": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6003193685204", "type": "string" }, "name": { "description": "Category name, such as `Movies`.", "example": "Car wash", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" } }, "title": "Detailed targeting", "type": "object" }, "AdGroupDevices": { "properties": { "operating_systems": { "items": { "$ref": "#/components/schemas/AdGroupOperatingSystem", "description": "Operating systems targeted. Empty targets all operating systems." }, "type": "array" }, "platforms": { "items": { "description": "Device types targeted. Empty targets all devices.", "enum": [ "mobile", "desktop" ], "example": "mobile", "type": "string" }, "type": "array" } }, "required": [ "platforms", "operating_systems" ], "type": "object" }, "AdGroupDevicesBody": { "description": "Device platforms and operating systems to target.", "properties": { "operating_systems": { "description": "Operating systems to target. Empty targets all operating systems.", "items": { "properties": { "minimum_version": { "description": "Lowest OS version to target, such as `18.0`. Omit to target any version.", "example": "18.0", "type": "string" }, "os": { "description": "Operating system to target.", "enum": [ "ios", "android" ], "example": "ios", "type": "string" } }, "required": [ "os" ], "type": "object" }, "type": "array" }, "platforms": { "description": "Device types to target. Empty targets all devices.", "items": { "enum": [ "mobile", "desktop" ], "example": "mobile", "type": "string" }, "type": "array" } }, "title": "Devices", "type": "object" }, "AdGroupFrequencyCap": { "properties": { "maximum_impressions": { "description": "Most times one person can be shown ads from this ad group within the window.", "example": 3, "type": "number" }, "per_days": { "description": "Length of the rolling window, in days.", "example": 7, "type": [ "number", "null" ] } }, "required": [ "maximum_impressions", "per_days" ], "type": "object" }, "AdGroupGeoLocations": { "properties": { "cities": { "items": { "$ref": "#/components/schemas/AdGroupCity", "description": "Cities, keyed by the ad platform's location taxonomy." }, "type": "array" }, "countries": { "items": { "description": "Countries, as ISO 3166-1 alpha-2 codes such as `US`.", "example": "US", "type": "string" }, "type": "array" }, "country_groups": { "items": { "description": "Multi-country groups such as `worldwide` or `europe`.", "example": "north_america", "type": "string" }, "type": "array" }, "custom_locations": { "items": { "$ref": "#/components/schemas/AdGroupCustomLocation", "description": "Circular areas, each a coordinate plus a radius." }, "type": "array" }, "regions": { "items": { "description": "US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.", "example": "US-TX", "type": "string" }, "type": "array" }, "zips": { "items": { "description": "ZIP and postal codes, keyed by the ad platform's location taxonomy. Meta keys these `COUNTRY:CODE`, as `US:78756`.", "example": "US:78756", "type": "string" }, "type": "array" } }, "required": [ "countries", "country_groups", "regions", "cities", "zips", "custom_locations" ], "type": "object" }, "AdGroupGeoLocationsBody": { "properties": { "cities": { "description": "Cities, keyed by the ad platform's location taxonomy.", "items": { "properties": { "key": { "description": "The ad platform's key for the city in its location taxonomy.", "example": "2418046", "type": "string" }, "name": { "description": "City name, such as `Austin`.", "example": "Austin", "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "countries": { "description": "Countries, as ISO 3166-1 alpha-2 codes such as `US`.", "items": { "example": "US", "type": "string" }, "type": "array" }, "country_groups": { "description": "Multi-country groups such as `worldwide` or `europe`. Include-only — groups can't be excluded.", "items": { "example": "north_america", "type": "string" }, "type": "array" }, "custom_locations": { "description": "Circular areas, each a coordinate plus a radius. At most 200 across include and exclude.", "items": { "properties": { "distance_unit": { "description": "Unit for `radius`. Defaults to `mile`.", "enum": [ "mile", "kilometer" ], "example": "mile", "type": "string" }, "latitude": { "description": "Latitude of the center point.", "example": 30.2672, "type": "number" }, "longitude": { "description": "Longitude of the center point.", "example": -97.7431, "type": "number" }, "name": { "description": "Label for the location, such as a city or address.", "example": "4180 Burnet Rd, Austin TX 78756", "type": "string" }, "radius": { "description": "Radius around the center point: 1-50 miles or 1-80 kilometers.", "example": 25, "type": "number" } }, "required": [ "latitude", "longitude", "radius" ], "type": "object" }, "type": "array" }, "regions": { "description": "US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.", "items": { "example": "US-TX", "type": "string" }, "type": "array" }, "zips": { "description": "ZIP and postal codes, keyed by the ad platform's location taxonomy. Meta keys these `COUNTRY:CODE`, as `US:78756` — a bare code is ambiguous, because the same one exists in several countries. TikTok takes the bare code.", "items": { "anyOf": [ { "type": "string" }, { "properties": { "key": { "description": "The ad platform's key for the ZIP or postal code.", "type": "string" } }, "required": [ "key" ], "type": "object" } ], "example": "US:78756" }, "type": "array" } }, "title": "Geo locations", "type": "object" }, "AdGroupOperatingSystem": { "properties": { "minimum_version": { "description": "Lowest OS version targeted, such as `18.0`. Absent when any version qualifies.", "example": "18.0", "type": "string" }, "os": { "description": "Operating system targeted.", "enum": [ "ios", "android" ], "example": "ios", "type": "string" } }, "required": [ "os" ], "type": "object" }, "AdGroupPlacement": { "properties": { "platform": { "description": "Publisher platform where the ad is eligible to appear.", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "example": "facebook", "type": "string" }, "positions": { "items": { "description": "Positions targeted within the platform, such as `feed` or `story`. Empty targets all of the platform's positions.", "example": "feed", "type": "string" }, "type": "array" } }, "required": [ "platform", "positions" ], "type": "object" }, "AdGroupRegions": { "properties": { "exclude": { "$ref": "#/components/schemas/AdGroupGeoLocations", "description": "Locations excluded from targeting. Country groups can't be excluded." }, "include": { "$ref": "#/components/schemas/AdGroupGeoLocations", "description": "Locations the ad group targets." } }, "required": [ "include", "exclude" ], "type": "object" }, "AdGroupRegionsBody": { "description": "Locations to target and exclude.", "properties": { "exclude": { "$ref": "#/components/schemas/AdGroupGeoLocationsBody", "description": "Locations excluded from targeting. Country groups can't be excluded." }, "include": { "$ref": "#/components/schemas/AdGroupGeoLocationsBody", "description": "Locations the ad group targets." } }, "title": "Regions", "type": "object" }, "AdGroupTargetingCategory": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6003193685204", "type": "string" }, "name": { "description": "Category name, such as `Movies`.", "example": "Car wash", "type": "string" } }, "required": [ "id" ], "type": "object" }, "AdLeadForm": { "properties": { "completion": { "description": "Screen shown after the form is submitted. `null` when the form uses the default.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormCompletion" }, { "type": "null" } ] }, "disclaimer": { "description": "Custom consent disclaimer shown before submission. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormDisclaimer" }, { "type": "null" } ] }, "form_type": { "description": "`more_volume` is quickest to submit; `higher_intent` adds a confirmation step before submission.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "intro": { "description": "Intro screen shown before the questions. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormIntro" }, { "type": "null" } ] }, "name": { "description": "Internal name of the form.", "example": "Ceramic coating quote requests", "type": [ "string", "null" ] }, "phone_verification": { "description": "Whether the phone number must be verified by SMS before submitting.", "example": true, "type": "boolean" }, "privacy_policy": { "description": "Your privacy policy, linked from the form. `null` when unset.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormPrivacyPolicy" }, { "type": "null" } ] }, "questions": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestion", "description": "Questions on the form, in order." }, "type": "array" } }, "required": [ "name", "form_type", "intro", "questions", "privacy_policy", "completion", "disclaimer", "phone_verification" ], "type": "object" }, "AdLeadFormCompletion": { "properties": { "button_text": { "description": "Text of the follow-up button.", "example": "See our work", "type": [ "string", "null" ] }, "description": { "description": "Body text under the headline.", "example": "We book coatings two days out, so pick a slot when we ring.", "type": [ "string", "null" ] }, "headline": { "description": "Headline of the completion screen.", "example": "Thanks — we will call you today", "type": [ "string", "null" ] }, "url": { "description": "Website the follow-up button opens. `null` when the screen has no button.", "example": "https://shinetime.example/gallery", "type": [ "string", "null" ] } }, "required": [ "headline", "description", "button_text", "url" ], "type": "object" }, "AdLeadFormDisclaimer": { "properties": { "body": { "description": "Disclaimer text.", "example": "Ceramic coating requires the vehicle for two days.", "type": [ "string", "null" ] }, "checkboxes": { "items": { "$ref": "#/components/schemas/AdLeadFormDisclaimerCheckbox", "description": "Consent checkboxes the person can tick. Empty when the disclaimer is text-only." }, "type": "array" }, "title": { "description": "Disclaimer title.", "example": "Before you submit", "type": [ "string", "null" ] } }, "required": [ "title", "body", "checkboxes" ], "type": "object" }, "AdLeadFormDisclaimerCheckbox": { "properties": { "checked_by_default": { "description": "Whether the checkbox starts ticked.", "example": false, "type": [ "boolean", "null" ] }, "key": { "description": "Stable identifier consent responses are stored under.", "example": "consent_1", "type": [ "string", "null" ] }, "required": { "description": "Whether the checkbox must be ticked to submit the form.", "example": true, "type": [ "boolean", "null" ] }, "text": { "description": "Consent text next to the checkbox.", "example": "I agree", "type": "string" } }, "required": [ "text", "key", "required", "checked_by_default" ], "type": "object" }, "AdLeadFormIntro": { "properties": { "description": { "description": "Body text under the headline.", "example": "Tell us about your vehicle and we will send a fixed price.", "type": [ "string", "null" ] }, "headline": { "description": "Headline of the intro screen.", "example": "Get a ceramic coating quote", "type": [ "string", "null" ] } }, "required": [ "headline", "description" ], "type": "object" }, "AdLeadFormOptionLogic": { "properties": { "action": { "description": "What happens when the choice is selected.", "enum": [ "go_to_question", "submit_form", "close_form" ], "example": "go_to_question", "type": "string" }, "target_end_page_index": { "description": "Zero-based index of the ending screen to jump to.", "example": 0, "type": "number" }, "target_question_index": { "description": "Zero-based index of the question to jump to, for `go_to_question`.", "example": 3, "type": "number" } }, "required": [ "action" ], "type": "object" }, "AdLeadFormPrivacyPolicy": { "properties": { "link_text": { "description": "Link text shown for the policy. `null` uses the platform default.", "example": "Shine Time privacy policy", "type": [ "string", "null" ] }, "url": { "description": "URL of your privacy policy.", "example": "https://shinetime.example/privacy", "type": "string" } }, "required": [ "url", "link_text" ], "type": "object" }, "AdLeadFormQuestion": { "properties": { "format": { "description": "Answer format for `custom` questions: `short_answer`, `multiple_choice`, or `appointment`. Absent otherwise.", "example": "multiple_choice", "type": "string" }, "label": { "description": "Question text for `custom` questions. Absent for standard prefill questions.", "example": "What vehicle are we detailing?", "type": "string" }, "options": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestionOption", "description": "Choices for `multiple_choice` questions. Absent for other formats." }, "type": "array" }, "type": { "description": "Question type: a standard prefill type such as `email`, `phone`, or `full_name`, or `custom` for your own question.", "example": "custom", "type": "string" } }, "required": [ "type" ], "type": "object" }, "AdLeadFormQuestionOption": { "properties": { "key": { "description": "Stable identifier the choice's answers are stored under. Absent for simple choices.", "example": "ceramic_coating", "type": [ "string", "null" ] }, "logic": { "$ref": "#/components/schemas/AdLeadFormOptionLogic", "description": "Where the form goes when this choice is selected. Absent when the form just continues to the next question." }, "value": { "description": "Choice text shown to the person.", "example": "Ceramic coating", "type": "string" } }, "required": [ "value" ], "type": "object" }, "AdMessagingConfig": { "properties": { "keyword": { "description": "Suggested reply the person can tap to start the conversation.", "example": "Book an interior deep clean", "type": [ "string", "null" ] }, "message": { "description": "Greeting shown when the conversation opens.", "example": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote.", "type": [ "string", "null" ] } }, "required": [ "message", "keyword" ], "type": "object" }, "AdPlatformIssue": { "properties": { "id": { "description": "Unique identifier for the issue.", "example": "adiss_xxxxxxxxxxxxxx", "type": "string" }, "message": { "description": "A description of what the issue is and how it can be resolved.", "example": "Your ad was rejected for unacceptable business practices. Edit the ad's content and resubmit.", "type": "string" }, "resource_id": { "description": "The ID of the campaign, ad group, or ad the issue is attached to.", "example": "ad_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "resource_type": { "description": "The type of resource the issue is attached to.", "enum": [ "ad_campaign", "ad_group", "ad" ], "example": "ad", "type": "string" } }, "required": [ "id", "message", "resource_id", "resource_type" ], "type": "object" }, "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" }, "ApiKey": { "properties": { "api_version_date": { "description": "Dated API version used when requests authenticated with this key omit the `Api-Version-Date` header.", "enum": [ "2025-01-01", "2026-06-08", "2026-06-09", "2026-06-20", "2026-07-01", "2026-07-08", "2026-07-08-1", "2026-07-18", "2026-07-20", "2026-07-22", "2026-07-23", "2026-07-25", "2026-07-26", "2026-07-27", "2026-07-29", "2026-07-29-1", "2026-07-31", "2026-08-03", "2026-08-05", "2026-08-05-1", "2026-08-10", "2026-08-12", "2026-08-13", "2026-08-14", "2026-08-21", "2026-08-21-1", "2026-08-25", "2026-08-25-1", "2026-08-25-2" ], "example": "2026-08-25-2", "type": "string" }, "created_at": { "description": "When the API key was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "expires_at": { "description": "When the API key stops working, as an ISO 8601 timestamp. `null` means it never expires.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "grants": { "items": { "$ref": "#/components/schemas/ApiKeyGrant", "description": "The key's effective permissions, grouped by resource. Present on retrieve, create, update, and rotate responses; omitted on list." }, "type": "array" }, "id": { "description": "API key ID, prefixed `apik_`.", "example": "apik_xxxxxxxxxxxxxx", "type": "string" }, "ip_allowlist": { "items": { "description": "IPv4/IPv6 CIDR ranges allowed to use this key. `null` or empty means requests are accepted from any IP.", "example": "203.0.113.0/24", "type": "string" }, "type": [ "array", "null" ] }, "is_default_for_resource": { "description": "Whether this is the resource's default API key. Default keys cannot be updated or deleted, only rotated.", "example": false, "type": "boolean" }, "name": { "description": "Human-readable name identifying the API key, or `null` when none was set.", "example": "Shine Time Booking (admin role)", "type": [ "string", "null" ] }, "obfuscated_secret_key": { "description": "Masked version of the secret key, so the key can be recognized without revealing the full secret.", "example": "apik_xxxx....xxxx", "type": "string" }, "secret_key": { "description": "The full secret used to authenticate requests. Returned only once, on create and rotate responses — store it immediately.", "example": "apik_xxxxxxxxxxxxxx_C0000_C_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "system_role": { "description": "System role the key inherits its permissions from, or `null` when it uses an explicit permissions policy. Only account API keys can use a system role.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", null ], "example": "admin", "type": [ "string", "null" ] }, "updated_at": { "description": "When the API key was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "name", "obfuscated_secret_key", "is_default_for_resource", "system_role", "api_version_date", "expires_at", "ip_allowlist", "created_at", "updated_at" ], "type": "object" }, "ApiKeyGrant": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/ApiKeyGrantAction", "description": "The actions the grant covers on the resource, each marked granted or not." }, "type": "array" }, "resource_id": { "description": "ID of the resource the actions apply to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "resource_type": { "description": "The type of resource the actions apply to, such as `account`, `product`, or `app`.", "example": "account", "type": "string" } }, "required": [ "resource_id", "resource_type", "actions" ], "type": "object" }, "ApiKeyGrantAction": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "ai_prompt:create", "type": "string" }, "granted": { "description": "Whether the key holds the action on the grant's resource.", "example": false, "type": "boolean" } }, "required": [ "action", "granted" ], "type": "object" }, "ApiVersion": { "description": "The different API versions", "enum": [ "v1", "v2", "v5" ], "type": "string" }, "App": { "properties": { "account": { "$ref": "#/components/schemas/AccountParent", "description": "The account that owns the app." }, "api_key": { "description": "Legacy app API key used to authenticate requests on the app's behalf. `null` when no key exists or the caller lacks the `developer:manage_api_key` permission.", "oneOf": [ { "$ref": "#/components/schemas/AppApiKey" }, { "type": "null" } ] }, "app_store_description": { "description": "Detailed description shown on the app store's in-depth app page, or `null` when none has been set.", "example": "Shine Time Booking turns a whop into a booking calendar. Members pick a package, choose a slot that fits the day's route, and pay up front. A reminder goes out the night before and the receipt lands as soon as the job is signed off.", "type": [ "string", "null" ] }, "app_type": { "description": "The type of end-user the app is built for.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "b2c_app", "type": "string" }, "banner_image": { "description": "Banner image from the app's product listing, or `null` when none is uploaded.", "oneOf": [ { "$ref": "#/components/schemas/AppBannerImage" }, { "type": "null" } ] }, "base_url": { "description": "The production base URL where the app is hosted. `null` if no base URL is configured, if the caller lacks the `developer:basic:read` permission on the app's account, or on list responses, which never expose it.", "example": "https://booking.shinetime.example", "type": [ "string", "null" ] }, "businesses_created_count": { "description": "Website businesses created from this app as a template.", "example": 5, "type": "integer" }, "businesses_created_logo_urls": { "items": { "description": "Up to three logo image URLs from businesses created from this app as a template.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "type": "array" }, "creator": { "$ref": "#/components/schemas/AppCreator", "description": "The user who owns the publishing account." }, "dashboard_path": { "description": "URL path for the account dashboard view, or `null` when not configured.", "example": "/dashboard/[companyId]", "type": [ "string", "null" ] }, "default_api_key": { "description": "The app's default API key. `null` when the app has no default key or the caller lacks the `developer:manage_api_key` permission; `secret_key` is additionally `null` unless the caller could have created the key themselves.", "oneOf": [ { "$ref": "#/components/schemas/AppDefaultApiKey" }, { "type": "null" } ] }, "deployment": { "description": "What the app has left to publish, and how a publish in flight is going — `status` is only ever `unpublished`, `publishing`, or `failed` here. `null` means there is nothing to report: the app is fully published, there is no working copy to publish from, or the caller cannot deploy this app. Tell those apart from the app's own `production_web_build`.", "oneOf": [ { "$ref": "#/components/schemas/AppDeployment" }, { "type": "null" } ] }, "description": { "description": "Short description shown in listings and search results, or `null` if none has been set.", "example": "Let members book a mobile detailing appointment without leaving your whop.", "type": [ "string", "null" ] }, "discover_path": { "description": "URL path for the discover view, or `null` when not configured.", "example": "/discover", "type": [ "string", "null" ] }, "domain_id": { "description": "Subdomain identifier for the app's proxied URL, forming https://{domain_id}.apps.whop.com.", "example": "whopappdomain0000001", "type": "string" }, "elements_used": { "items": { "description": "Whop Elements the app's production web build mounts, as `.` keys (sub-controller children take a third segment, e.g. `payments.cardFields.cardNumber`). A bare namespace means the build reaches that namespace but the individual elements could not be resolved. Empty when the build mounts none, when it has not been scanned yet, or when the app has no production web build.", "enum": [ "ads", "ads.billing-setup", "ads.campaign-creator", "ads.reporting", "ads.reporting.chart", "ads.reporting.table", "checkout", "checkout.checkout", "checkout.expressCheckout", "payments", "payments.address", "payments.branding", "payments.card", "payments.cardFields", "payments.cardFields.cardCvc", "payments.cardFields.cardExpiry", "payments.cardFields.cardNumber", "payments.email", "payments.payment", "payments.taxId", "tracking", "tracking.events", "tracking.people", "wallet", "wallet.activity", "wallet.balances", "wallet.balances.balance", "wallet.balances.list", "wallet.cards", "wallet.deposit", "wallet.send", "wallet.withdraw", "websites", "websites.pixel-setup", "websites.websites" ], "example": "ads", "type": "string" }, "type": "array" }, "experience_path": { "description": "URL path for the member-facing hub view, or `null` when not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "hosted_url": { "description": "Full URL where the app's hosted web build is served, or `null` if no route is claimed.", "example": "https://shine-time-booking.whop.site", "type": [ "string", "null" ] }, "icon": { "$ref": "#/components/schemas/AppIcon", "description": "The app's icon. Falls back to the default app icon when none is uploaded." }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "marketplace_status": { "description": "Approval status of the app's product listing on the Whop app store, or `null` when the app has no associated product.", "enum": [ "not_available", "pending_review", "live_marketplace", null ], "example": "not_available", "type": [ "string", "null" ] }, "name": { "description": "Display name shown on the app store and in experience navigation.", "example": "Shine Time Booking", "type": "string" }, "oauth_client_type": { "description": "How the app authenticates at the OAuth token endpoint.", "enum": [ "public", "confidential" ], "example": "public", "type": "string" }, "openapi_path": { "description": "URL path to the app's OpenAPI spec file, or `null` when not configured.", "example": "/openapi.json", "type": [ "string", "null" ] }, "origin": { "description": "Full origin URL of the app's proxied domain, for example https://ab1c2d3e4f.apps.whop.com.", "example": "https://whopappdomain0000001.apps.whop.com", "type": [ "string", "null" ] }, "preview_token": { "description": "A short-lived signed pass scoping the caller to this app's gated preview hosts — every build preview and the live dev-server sandbox. Add it to a preview host as the `__whop_preview` query param (or `x-whop-preview-token` header). `null` unless the caller is a team member who can read the app's developer settings.", "example": "whop_preview_pass_example", "type": [ "string", "null" ] }, "product_id": { "description": "ID of the app's product listing on the Whop app store, or `null` when the app has no associated product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "production_android_build": { "description": "The approved build currently served on Android, or `null` when none is deployed.", "oneOf": [ { "$ref": "#/components/schemas/AppProductionBuild" }, { "type": "null" } ] }, "production_ios_build": { "description": "The approved build currently served on iOS, or `null` when none is deployed.", "oneOf": [ { "$ref": "#/components/schemas/AppProductionBuild" }, { "type": "null" } ] }, "production_web_build": { "description": "The approved build currently served on web, or `null` when none is deployed.", "oneOf": [ { "$ref": "#/components/schemas/AppProductionBuild" }, { "type": "null" } ] }, "redirect_uris": { "items": { "description": "Whitelisted OAuth callback URLs users are redirected to after authorizing the app.", "example": "https://booking.shinetime.example/oauth/callback", "type": "string" }, "type": "array" }, "requested_permissions": { "items": { "$ref": "#/components/schemas/AppRequestedPermission", "description": "Permissions the app requests on install." }, "type": "array" }, "required_scopes": { "items": { "description": "Scopes the app asks a user to grant when they authorize it, shown on the consent screen.", "enum": [ "read_user" ], "example": "read_user", "type": "string" }, "type": "array" }, "route": { "description": "Claimed subdomain route where hosted web builds are served (`myapp` for myapp.whop.site), or `null` if no route is claimed.", "example": "shine-time-booking", "type": [ "string", "null" ] }, "secrets": { "description": "The app's production secrets as an object of string values, injected into the hosted server runtime. `null` when the caller lacks the `developer:update_app` permission.", "example": { "BOOKING_CALENDAR_ID": "cal_9f21" }, "type": [ "object", "null" ] }, "skills_path": { "description": "URL path to the app's skills directory, or `null` when not configured.", "example": "/skills", "type": [ "string", "null" ] }, "status": { "description": "Visibility on the Whop app store: `live` is publicly discoverable, `unlisted` is accessible only via direct link, `hidden` is not visible anywhere.", "enum": [ "live", "unlisted", "hidden" ], "example": "unlisted", "type": "string" }, "verified": { "description": "Whether the app has been verified by Whop and is eligible for the featured apps section.", "example": false, "type": "boolean" } }, "required": [ "id", "name", "description", "status", "base_url", "domain_id", "route", "hosted_url", "verified", "app_type", "origin", "experience_path", "discover_path", "dashboard_path", "skills_path", "openapi_path", "account", "icon", "banner_image", "creator", "businesses_created_count", "businesses_created_logo_urls", "app_store_description", "requested_permissions", "api_key", "default_api_key", "production_web_build", "production_ios_build", "production_android_build", "redirect_uris", "required_scopes", "secrets", "product_id", "marketplace_status", "oauth_client_type", "deployment", "elements_used", "preview_token" ], "type": "object" }, "AppApiKey": { "properties": { "created_at": { "description": "When the key was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "token": { "description": "The key's secret token, sent as a bearer token to authenticate requests on the app's behalf.", "example": "eyJhbGciOiJFUzI1NiJ9.xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "token", "created_at" ], "type": "object" }, "AppBannerImage": { "properties": { "url": { "description": "Banner image URL, taken from the app's product listing.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "url" ], "type": "object" }, "AppBuild": { "properties": { "checksum": { "description": "Client-generated checksum of the build file, used to verify file integrity.", "example": "xxxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the build was uploaded, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "file_url": { "description": "URL to download the uploaded build artifact.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "App build ID, prefixed `abld_`.", "example": "apbu_xxxxxxxxxxxxxx", "type": "string" }, "is_production": { "description": "Whether this build is the currently active production build for its platform.", "example": false, "type": "boolean" }, "platform": { "description": "The target platform for this build.", "enum": [ "ios", "android", "web" ], "example": "ios", "type": "string" }, "review_message": { "description": "Feedback from the reviewer explaining a rejection, or `null` if the build has not been reviewed or was approved.", "example": "The hub view crashes on launch when the member has no active membership. Fix and resubmit.", "type": [ "string", "null" ] }, "source_url": { "description": "URL to download the compressed source code archive that produced this build, or `null` when the build was uploaded without a source archive.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "The build's review status.", "enum": [ "draft", "pending", "approved", "rejected" ], "example": "rejected", "type": "string" }, "supported_app_view_types": { "items": { "description": "The view types this build supports, as declared by the developer.", "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "example": "hub", "type": "string" }, "type": "array" } }, "required": [ "id", "platform", "file_url", "source_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" ] }, "source_url": { "description": "A URL to download the compressed source code archive that produced this build. Null if the build was uploaded without a source archive.", "example": "https://cdn.whop.com/builds/abc123-source.zip", "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", "source_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" }, "AppCreator": { "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "Public username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "AppDefaultApiKey": { "properties": { "id": { "description": "API key ID, prefixed `apik_`.", "example": "apik_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable name identifying the API key, or `null` when none was set.", "example": "Default", "type": [ "string", "null" ] }, "obfuscated_secret_key": { "description": "Masked version of the secret key, so the key can be recognized without revealing the full secret.", "example": "apik_xxxx....xxxx", "type": "string" }, "secret_key": { "description": "The full secret used to authenticate requests. `null` unless the caller could have created the key themselves.", "example": "apik_xxxxxxxxxxxxxx_C0000_C_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "name", "obfuscated_secret_key", "secret_key" ], "type": "object" }, "AppDeployment": { "properties": { "app_id": { "description": "The app being deployed, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "build_id": { "description": "The build the deployment produced, prefixed `abld_`, or `null` until it succeeds.", "type": [ "string", "null" ] }, "draft": { "description": "Whether the running or last deployment uploaded a build without making it live.", "example": false, "type": "boolean" }, "error": { "description": "Why the deployment failed, or `null` when it did not.", "type": [ "string", "null" ] }, "estimated_duration_ms": { "description": "How long this deployment is expected to take in total, estimated from previous runs.", "example": 150000, "type": [ "integer", "null" ] }, "estimated_remaining_ms": { "description": "How much longer the deployment is expected to take. Held above zero until it actually finishes.", "example": 91000, "type": [ "integer", "null" ] }, "finished_at": { "description": "When the deployment ended, in milliseconds since the epoch, or `null` while it is still running.", "type": [ "integer", "null" ] }, "phase": { "description": "The stage a running deployment has reached, or `null` when none is running. Later phases dominate the wall clock: `process_archive` waits on the upload pipeline and `promote` waits for the build to go live.", "enum": [ "install", "build", "typecheck", "upload_build", "upload_source", "process_archive", "create_build", "promote", null ], "example": "process_archive", "type": [ "string", "null" ] }, "progress": { "description": "Fraction of the deployment estimated to be complete, from 0 to 1. Stops just short of 1 until the run ends.", "example": 0.39, "type": [ "number", "null" ] }, "started_at": { "description": "When the deployment began, in milliseconds since the epoch, or `null` when none has run.", "example": 1767268800000, "type": [ "integer", "null" ] }, "status": { "description": "Whether the app has anything to publish, and what a publish in flight is doing. `unpublished` means publishing would ship something new; `no_source` means the sandbox holds no copy of this app, so there is nothing to publish from.", "enum": [ "published", "unpublished", "publishing", "failed", "no_source" ], "example": "publishing", "type": "string" }, "url": { "description": "Where the deployed site is served, or `null` unless the deployment went live.", "type": [ "string", "null" ] } }, "required": [ "app_id", "status", "draft", "phase", "started_at", "finished_at", "estimated_duration_ms", "estimated_remaining_ms", "progress", "build_id", "url", "error" ], "type": "object" }, "AppIcon": { "properties": { "url": { "description": "Icon image URL. Always present — the default app icon when none is uploaded.", "example": "https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev/custom-perk-icon.svg", "type": "string" } }, "required": [ "url" ], "type": "object" }, "AppListItem": { "properties": { "account": { "$ref": "#/components/schemas/AccountParent", "description": "The account that owns the app." }, "app_type": { "description": "The type of end-user the app is built for.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "b2c_app", "type": "string" }, "banner_image": { "description": "Banner image from the app's product listing, or `null` when none is uploaded.", "oneOf": [ { "$ref": "#/components/schemas/AppBannerImage" }, { "type": "null" } ] }, "base_url": { "description": "The production base URL where the app is hosted. `null` if no base URL is configured, if the caller lacks the `developer:basic:read` permission on the app's account, or on list responses, which never expose it.", "type": [ "string", "null" ] }, "businesses_created_count": { "description": "Number of businesses created from this app as a template.", "example": 0, "type": "integer" }, "businesses_created_logo_urls": { "items": { "description": "Up to three logo image URLs from businesses created from this app as a template.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "type": "array" }, "creator": { "$ref": "#/components/schemas/AppCreator", "description": "The user who owns the publishing account." }, "dashboard_path": { "description": "URL path for the account dashboard view, or `null` when not configured.", "example": "/dashboard/[companyId]", "type": [ "string", "null" ] }, "description": { "description": "Short description shown in listings and search results, or `null` if none has been set.", "example": "Let members book a mobile detailing appointment without leaving your whop.", "type": [ "string", "null" ] }, "discover_path": { "description": "URL path for the discover view, or `null` when not configured.", "example": "/discover", "type": [ "string", "null" ] }, "domain_id": { "description": "Subdomain identifier for the app's proxied URL, forming https://{domain_id}.apps.whop.com.", "example": "whopappdomain0000001", "type": "string" }, "experience_path": { "description": "URL path for the member-facing hub view, or `null` when not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "hosted_url": { "description": "Full URL where the app's hosted web build is served, or `null` if no route is claimed.", "example": "https://shine-time-booking.whop.site", "type": [ "string", "null" ] }, "icon": { "$ref": "#/components/schemas/AppIcon", "description": "The app's icon. Falls back to the default app icon when none is uploaded." }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name shown on the app store and in experience navigation.", "example": "Shine Time Booking", "type": "string" }, "openapi_path": { "description": "URL path to the app's OpenAPI spec file, or `null` when not configured.", "example": "/openapi.json", "type": [ "string", "null" ] }, "origin": { "description": "Full origin URL of the app's proxied domain, for example https://ab1c2d3e4f.apps.whop.com.", "example": "https://whopappdomain0000001.apps.whop.com", "type": [ "string", "null" ] }, "route": { "description": "Claimed subdomain route where hosted web builds are served (`myapp` for myapp.whop.site), or `null` if no route is claimed.", "example": "shine-time-booking", "type": [ "string", "null" ] }, "skills_path": { "description": "URL path to the app's skills directory, or `null` when not configured.", "example": "/skills", "type": [ "string", "null" ] }, "status": { "description": "Visibility on the Whop app store: `live` is publicly discoverable, `unlisted` is accessible only via direct link, `hidden` is not visible anywhere.", "enum": [ "live", "unlisted", "hidden" ], "example": "unlisted", "type": "string" }, "verified": { "description": "Whether the app has been verified by Whop and is eligible for the featured apps section.", "example": false, "type": "boolean" } }, "required": [ "id", "name", "description", "status", "base_url", "domain_id", "route", "hosted_url", "verified", "app_type", "origin", "experience_path", "discover_path", "dashboard_path", "skills_path", "openapi_path", "account", "icon", "banner_image", "creator", "businesses_created_count", "businesses_created_logo_urls" ], "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" }, "AppProductionBuild": { "properties": { "checksum": { "description": "Client-generated checksum of the build file, used to verify file integrity.", "example": "xxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "file_url": { "description": "URL to download the uploaded build artifact.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "App build ID, prefixed `abld_`.", "example": "apbu_xxxxxxxxxxxxxx", "type": "string" }, "source_url": { "description": "URL to download the compressed source code archive that produced this build, or `null` when the build was uploaded without a source archive.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "The build's review status.", "enum": [ "draft", "pending", "approved", "rejected" ], "example": "approved", "type": "string" } }, "required": [ "id", "file_url", "source_url", "checksum", "status" ], "type": "object" }, "AppRequestedPermission": { "properties": { "is_required": { "description": "Whether the app requires the permission to be granted on install, as opposed to requesting it optionally.", "example": true, "type": "boolean" }, "justification": { "description": "The developer's explanation of why the app needs the permission, or `null` when none was provided.", "example": "Creates apps on behalf of the installing company.", "type": [ "string", "null" ] }, "permission_action": { "$ref": "#/components/schemas/AppRequestedPermissionAction", "description": "The permission action the app requests." } }, "required": [ "permission_action", "is_required", "justification" ], "type": "object" }, "AppRequestedPermissionAction": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "company:basic:read", "type": "string" }, "name": { "description": "Human-readable name of the action.", "example": "company:basic:read", "type": "string" } }, "required": [ "action", "name" ], "type": "object" }, "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", "website" ], "type": "string" }, "AppUsageStats": { "properties": { "dau": { "description": "Daily active users.", "type": [ "integer", "null" ] }, "mau": { "description": "Monthly active users.", "type": [ "integer", "null" ] }, "time_spent_last24_hours": { "description": "Total time users spent in the app over the last 24 hours, in seconds.", "type": [ "integer", "null" ] }, "wau": { "description": "Weekly active users.", "type": [ "integer", "null" ] } }, "required": [ "dau", "wau", "mau", "time_spent_last24_hours" ], "type": "object" }, "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" }, "Audience": { "properties": { "audience_type": { "description": "`custom` = a customer list (uploaded, or built from saved People filters); `lookalike` = Meta lookalike built from a custom audience.", "enum": [ "custom", "lookalike" ], "example": "lookalike", "type": "string" }, "auto_refresh": { "description": "Whether membership keeps updating. `true` rebuilds it from the saved filters twice a day, so people join and leave as they start and stop matching. `false` keeps whoever matched when it was built and never rebuilds. Always `false` for uploaded lists and lookalikes.", "example": false, "type": "boolean" }, "created_at": { "description": "When the audience was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "error_message": { "description": "Processing error message. `null` unless processing is partial or failed.", "example": "412 of 1,000 rows had no email or phone number, so the list could not be matched.", "type": [ "string", "null" ] }, "filters": { "description": "For audiences built from People filters: the filters that define membership, keyed exactly as `GET /people` accepts them — for example `{\"os\": \"iOS\", \"country\": \"US\"}`. `null` for uploaded lists and lookalikes.", "example": { "country": "US", "last_seen_within_days": 30 }, "type": [ "object", "null" ] }, "id": { "description": "Audience ID, prefixed `adaud_`.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "last_refreshed_at": { "description": "When the audience membership was last rebuilt, as an ISO 8601 timestamp. `null` until the first build completes.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "lookalike_ratio": { "description": "For lookalikes: the upper bound of the similarity band as a fraction (0.02 = top 2%). `null` for custom audiences.", "example": 0.04, "type": [ "number", "null" ] }, "lookalike_starting_ratio": { "description": "For lookalikes: the lower bound of the similarity band as a fraction. `null` for custom audiences and first-tier lookalikes.", "example": 0.02, "type": [ "number", "null" ] }, "match_rates": { "items": { "$ref": "#/components/schemas/AudienceMatchRate", "description": "Estimated match rates by ad platform. Empty when the audience was not sent to a supported platform." }, "type": "array" }, "matched_rows": { "description": "Members successfully uploaded to connected ad accounts. Always 0 for lookalikes.", "example": 0, "type": "number" }, "name": { "description": "Audience display name.", "example": "Past purchasers Lookalike 2–4%", "type": "string" }, "platform_audience_ids": { "items": { "description": "External audience IDs created on connected ad platforms, such as Meta.", "example": "120246230799130687", "type": "string" }, "type": "array" }, "processed_rows": { "description": "Members processed from the source so far. Always 0 for lookalikes.", "example": 0, "type": "number" }, "progress_percent": { "description": "Processing progress from 0 to 100.", "example": 0, "type": "number" }, "source_audience_id": { "description": "For lookalikes: the audience this lookalike was built from. `null` for custom audiences.", "example": "adaud_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source_type": { "description": "Where members come from. `csv_upload` = an uploaded customer list; `people_filter` = built from saved People filters. See `auto_refresh` for whether a `people_filter` audience keeps updating.", "enum": [ "csv_upload", "people_filter" ], "example": "csv_upload", "type": "string" }, "status": { "description": "Current state of the audience import. `syncing` means Whop is sending matched rows to connected ad accounts. When status is `partial` or `failed`, `error_message` explains what went wrong.", "enum": [ "pending", "processing", "syncing", "ready", "partial", "failed" ], "type": "string" }, "total_rows": { "description": "Total members detected in the source — CSV rows for uploaded lists, matching people for automatic audiences. Always 0 for lookalikes.", "example": 0, "type": "number" }, "updated_at": { "description": "When the audience was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "name", "audience_type", "source_type", "status", "total_rows", "processed_rows", "matched_rows", "progress_percent", "error_message", "platform_audience_ids", "source_audience_id", "lookalike_ratio", "lookalike_starting_ratio", "filters", "auto_refresh", "last_refreshed_at", "created_at", "updated_at", "match_rates" ], "type": "object" }, "AudienceMatchRate": { "properties": { "lower_bound": { "description": "Lower bound of the estimated match rate percentage. `null` until available.", "example": 40.0, "type": [ "number", "null" ] }, "platform": { "description": "The ad platform that provided the match-rate estimate.", "enum": [ "meta" ], "example": "meta", "type": "string" }, "status": { "description": "Availability of the estimated match rate.", "enum": [ "calculating", "available", "unavailable", null ], "example": "available", "type": [ "string", "null" ] }, "upper_bound": { "description": "Upper bound of the estimated match rate percentage. `null` until available.", "example": 50.0, "type": [ "number", "null" ] } }, "required": [ "platform", "status", "lower_bound", "upper_bound" ], "type": "object" }, "AuthorizedUser": { "description": "A user who belongs to a company's team with access determined by their assigned role.", "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 belongs to a company's team with access determined by their assigned role.", "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", "workforce", "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": { "properties": { "accepted_deliverable_types": { "items": { "description": "The deliverable shapes this bounty accepts. Every bounty accepts any combination of `content_url` (posted links) and `media` (uploaded files), except `data_capture` bounties, whose proof is clips recorded in the Whop app that accumulate on the attempt.", "enum": [ "content_url", "media", "data_capture" ], "example": "data_capture", "type": "string" }, "type": "array" }, "accepted_submissions_count": { "description": "Submissions accepted so far.", "example": 0, "type": "integer" }, "accepted_submissions_limit": { "description": "Number of submissions that can be accepted (winner slots).", "example": 3, "type": "integer" }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`.", "example": 1, "type": "integer" }, "active_proof_livestream_feeds": { "items": { "$ref": "#/components/schemas/BountyActiveLivestreamFeed", "description": "Proof livestreams live on this bounty right now, newest first — workers streaming their attempts. Empty when nothing is live." }, "type": "array" }, "affiliate_share_amount": { "description": "What a referrer earns per accepted submission when the worker arrived through their affiliate link, in whole currency units, at the standard platform fee rate. Taken out of the worker's post-fee reward rather than added on top. `0` when the bounty pays no affiliate share, including bounties tied to no account, which cannot record a referral.", "example": 5.6, "type": "number" }, "allowed_country_codes": { "items": { "description": "Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "example": "US", "type": "string" }, "type": "array" }, "awaiting_review_submissions_count": { "description": "Submissions delivered and waiting on review. A subset of `unresolved_submissions_count`, which also counts attempts still in progress.", "example": 0, "type": "integer" }, "budget_amount": { "description": "Total gross budget committed to the bounty: `gross_reward_amount` times `accepted_submissions_limit`.", "example": 120.0, "type": "number" }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once at create. `null` for bounties created before the taxonomy rolled out.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other", null ], "example": "data_capture", "type": [ "string", "null" ] }, "cancel_requested_at": { "description": "When cancellation was requested, as an ISO 8601 timestamp. On a `closed` bounty this means the cancel is pending: submissions are stopped and the bounty cancels once in-flight submissions resolve. On a `canceled` bounty it records when the cancellation was requested. `null` when no cancellation was ever requested.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "capture_spec": { "description": "The technical contract footage must be recorded against. Present only on `data_capture` bounties; `null` for every other goal type.", "oneOf": [ { "$ref": "#/components/schemas/CaptureSpec" }, { "type": "null" } ] }, "created_at": { "description": "When the bounty was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency for all amounts on the bounty, as a lowercase ISO 4217 code.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "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", "cny", "kzt", "awg" ], "example": "usd", "type": "string" }, "denied_submissions_count": { "description": "Submissions reviewed and turned down.", "example": 0, "type": "integer" }, "description": { "description": "Full task instructions shown to workers.", "example": "Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.", "type": "string" }, "discussion_experience_id": { "description": "Experience the bounty's discussion thread lives in, prefixed `exp_`. Read this — not `experience_id` — to open the thread: a platform-wide bounty has no hosting experience of its own but its discussion still lives in one.", "type": [ "string", "null" ] }, "discussion_feed_id": { "description": "Forum feed containing the bounty's discussion thread. `null` for a bounty with no forum post.", "type": [ "string", "null" ] }, "discussion_post_id": { "description": "Forum post anchoring the bounty's discussion thread. Read together with `discussion_experience_id` to address the thread. `null` for a bounty with no forum post.", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the bounty is hosted in, prefixed `exp_`. `null` for platform-wide bounties; may belong to a different account than the funder.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "funding_account": { "description": "Account whose balance funds the bounty pool, or `null` when a user funds it personally. May differ from the account hosting `experience_id`.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "gross_paid_out_amount": { "description": "Gross amount paid out from the bounty pool across accepted submissions — worker payouts, platform fees, and affiliate shares together. Tips and reviewer rewards are excluded.", "example": 0.0, "type": "number" }, "gross_reward_amount": { "description": "Gross bounty-pool amount allocated per accepted submission, in whole currency units.", "example": 40.0, "type": "number" }, "hosting_account": { "description": "Account hosting the bounty's forum — the one whose `route` and `experience_id` address its discussion thread, and where its submissions dashboard lives. `null` for a platform-wide bounty with no host. May differ from `funding_account`.", "oneOf": [ { "$ref": "#/components/schemas/StorefrontAccount" }, { "type": "null" } ] }, "id": { "description": "Bounty ID, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate before it can be submitted, in seconds. Always a whole number of hours. Present only on `data_capture` bounties — it is what `net_reward_amount` pays for, so rate displays divide by it. `null` for every other goal type.", "example": 14400, "type": [ "integer", "null" ] }, "net_reward_amount": { "description": "What a worker is quoted per accepted submission after the platform fee, in whole currency units. The exact post-fee figure, at the standard platform fee rate — a worker who locked a different rate, or who arrived through an affiliate link, is paid a different amount.", "example": 28.0, "type": "number" }, "poster": { "$ref": "#/components/schemas/UserSummary", "description": "User who posted the bounty — the account owner when created with an account API key." }, "scheduled_frequency": { "description": "How often the schedule creates a new bounty. Each occurrence is a separate bounty; the original is not republished.", "enum": [ "once", "hourly", "daily", "weekly", "monthly", null ], "example": "weekly", "type": [ "string", "null" ] }, "scheduled_publish_at": { "description": "When a scheduled bounty will publish, as an ISO 8601 timestamp. `null` once published, for bounties that were never scheduled, and for terminally failed drafts parked for manual rescheduling.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "spots_remaining": { "description": "Unfilled winner capacity: `accepted_submissions_limit` minus `accepted_submissions_count`, clamped to zero. Not on its own a signal that the bounty accepts new claims — read `status` for that: only an `open` bounty takes new submissions.", "example": 3, "type": "integer" }, "status": { "description": "Lifecycle state. `scheduled` bounties are unpublished drafts, visible to their poster and the account's authorized managers; `open` bounties accept new submissions; `closed` bounties are live but no longer accept new submissions; `completed` bounties paid out every winner slot; `canceled` bounties ended before filling their slots.", "enum": [ "scheduled", "open", "closed", "completed", "canceled" ], "example": "scheduled", "type": "string" }, "submissions_closed_at": { "description": "When new submissions stopped being accepted, as an ISO 8601 timestamp. Set when a cancellation is requested on a bounty with work in flight, so in-flight submissions can resolve before the bounty cancels. `null` when submissions were never stopped — including completed bounties that simply filled every winner slot.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "title": { "description": "Short name of the task shown to workers.", "example": "Record interior detailing passes", "type": "string" }, "unresolved_submissions_count": { "description": "Submissions still awaiting an outcome: in progress or pending review.", "example": 0, "type": "integer" }, "updated_at": { "description": "When the bounty was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewer_accepted_submissions_count": { "description": "How many winner slots the authenticated user has already won on this bounty. Read against `accepted_submissions_per_user_limit` to show a worker their remaining allowance. `0` when the request has no authenticated user.", "example": 0, "type": "integer" } }, "required": [ "id", "title", "description", "status", "currency", "gross_reward_amount", "net_reward_amount", "affiliate_share_amount", "budget_amount", "gross_paid_out_amount", "accepted_submissions_limit", "accepted_submissions_per_user_limit", "accepted_submissions_count", "unresolved_submissions_count", "viewer_accepted_submissions_count", "spots_remaining", "business_goal_type", "accepted_deliverable_types", "min_total_verified_duration_seconds", "allowed_country_codes", "submissions_closed_at", "cancel_requested_at", "scheduled_publish_at", "scheduled_frequency", "experience_id", "discussion_post_id", "discussion_feed_id", "discussion_experience_id", "created_at", "updated_at", "capture_spec", "awaiting_review_submissions_count", "denied_submissions_count", "poster", "funding_account", "hosting_account", "active_proof_livestream_feeds" ], "type": "object" }, "BountyActiveLivestreamFeed": { "properties": { "host": { "description": "User hosting the proof livestream — the worker streaming their attempt. `null` if the host account no longer exists.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] }, "id": { "description": "Livestream feed ID.", "type": "string" }, "title": { "description": "Display title for the proof livestream.", "type": "string" } }, "required": [ "id", "title", "host" ], "type": "object" }, "BountyCaptureClip": { "properties": { "bounty_submission_id": { "description": "The bounty submission (attempt) this clip belongs to, prefixed `btys_`.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the clip was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "duration_seconds": { "description": "Server-validated clip duration in whole seconds. `null` until validation completes.", "example": 180, "type": [ "integer", "null" ] }, "failure_code": { "description": "Stable validation failure code. `null` unless `status` is `failed`.", "example": "upload_failed", "type": [ "string", "null" ] }, "failure_message": { "description": "Human-readable validation failure reason. `null` unless `status` is `failed`.", "example": "video: The video upload failed after 5 retries.", "type": [ "string", "null" ] }, "frames_url": { "description": "Temporary signed URL for the video frame timestamp log. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "Capture clip ID, prefixed `bclip_`.", "example": "bclip_xxxxxxxxxxxxxx", "type": "string" }, "imu_url": { "description": "Temporary signed URL for the IMU (accelerometer + gyroscope) log. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "manifest_url": { "description": "Temporary signed URL for the capture manifest. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "ready_at": { "description": "When server-side validation completed successfully, as an ISO 8601 timestamp. `null` until then.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "sequence": { "description": "The clip's stable order within the attempt, starting at 1.", "example": 1, "type": "integer" }, "status": { "description": "Recording and validation state. `recording` is still capturing; `verifying` is running server-side validation; `ready` passed validation and counts toward the verified-duration payout gate; `failed` did not validate.", "enum": [ "recording", "verifying", "ready", "failed" ], "example": "ready", "type": "string" }, "updated_at": { "description": "When the clip was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "video_url": { "description": "Temporary signed URL for the synchronized MP4 video. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "bounty_submission_id", "sequence", "status", "duration_seconds", "failure_code", "failure_message", "ready_at", "video_url", "imu_url", "frames_url", "manifest_url", "created_at", "updated_at" ], "type": "object" }, "BountyListItem": { "properties": { "accepted_deliverable_types": { "items": { "description": "The deliverable shapes this bounty accepts. Every bounty accepts any combination of `content_url` (posted links) and `media` (uploaded files), except `data_capture` bounties, whose proof is clips recorded in the Whop app that accumulate on the attempt.", "enum": [ "content_url", "media", "data_capture" ], "example": "content_url", "type": "string" }, "type": "array" }, "accepted_submissions_count": { "description": "Submissions accepted so far.", "example": 0, "type": "integer" }, "accepted_submissions_limit": { "description": "Number of submissions that can be accepted (winner slots).", "example": 1, "type": "integer" }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`.", "example": 1, "type": "integer" }, "affiliate_share_amount": { "description": "What a referrer earns per accepted submission when the worker arrived through their affiliate link, in whole currency units, at the standard platform fee rate. Taken out of the worker's post-fee reward rather than added on top. `0` when the bounty pays no affiliate share, including bounties tied to no account, which cannot record a referral.", "example": 2.1, "type": "number" }, "allowed_country_codes": { "items": { "description": "Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "example": "US", "type": "string" }, "type": "array" }, "budget_amount": { "description": "Total gross budget committed to the bounty: `gross_reward_amount` times `accepted_submissions_limit`.", "example": 15.0, "type": "number" }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once at create. `null` for bounties created before the taxonomy rolled out.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other", null ], "example": "clipping", "type": [ "string", "null" ] }, "cancel_requested_at": { "description": "When cancellation was requested, as an ISO 8601 timestamp. On a `closed` bounty this means the cancel is pending: submissions are stopped and the bounty cancels once in-flight submissions resolve. On a `canceled` bounty it records when the cancellation was requested. `null` when no cancellation was ever requested.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "When the bounty was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency for all amounts on the bounty, as a lowercase ISO 4217 code.", "example": "usd", "type": "string" }, "description": { "description": "Full task instructions shown to workers.", "example": "Bounty Description", "type": "string" }, "discussion_experience_id": { "description": "Experience the bounty's discussion thread lives in, prefixed `exp_`. Read this — not `experience_id` — to open the thread: a platform-wide bounty has no hosting experience of its own but its discussion still lives in one.", "type": [ "string", "null" ] }, "discussion_feed_id": { "description": "Forum feed containing the bounty's discussion thread. `null` for a bounty with no forum post.", "type": [ "string", "null" ] }, "discussion_post_id": { "description": "Forum post anchoring the bounty's discussion thread. Read together with `discussion_experience_id` to address the thread. `null` for a bounty with no forum post.", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the bounty is hosted in, prefixed `exp_`. `null` for platform-wide bounties; may belong to a different account than the funder.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "funding_account": { "description": "Account whose balance funds the bounty pool, or `null` when a user funds it personally. May differ from the account hosting `experience_id`.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "gross_paid_out_amount": { "description": "Gross amount paid out from the bounty pool across accepted submissions — worker payouts, platform fees, and affiliate shares together. Tips and reviewer rewards are excluded.", "example": 0.0, "type": "number" }, "gross_reward_amount": { "description": "Gross bounty-pool amount allocated per accepted submission, in whole currency units.", "example": 15.0, "type": "number" }, "hosting_account": { "description": "Account hosting the bounty's forum — the one whose `route` and `experience_id` address its discussion thread, and where its submissions dashboard lives. `null` for a platform-wide bounty with no host. May differ from `funding_account`.", "oneOf": [ { "$ref": "#/components/schemas/StorefrontAccount" }, { "type": "null" } ] }, "id": { "description": "Bounty ID, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate before it can be submitted, in seconds. Always a whole number of hours. Present only on `data_capture` bounties — it is what `net_reward_amount` pays for, so rate displays divide by it. `null` for every other goal type.", "type": [ "integer", "null" ] }, "net_reward_amount": { "description": "What a worker is quoted per accepted submission after the platform fee, in whole currency units. The exact post-fee figure, at the standard platform fee rate — a worker who locked a different rate, or who arrived through an affiliate link, is paid a different amount.", "example": 10.5, "type": "number" }, "poster": { "$ref": "#/components/schemas/UserSummary", "description": "User who posted the bounty — the account owner when created with an account API key." }, "scheduled_frequency": { "description": "How often the schedule creates a new bounty. Each occurrence is a separate bounty; the original is not republished.", "enum": [ "once", "hourly", "daily", "weekly", "monthly", null ], "example": "once", "type": [ "string", "null" ] }, "scheduled_publish_at": { "description": "When a scheduled bounty will publish, as an ISO 8601 timestamp. `null` once published, for bounties that were never scheduled, and for terminally failed drafts parked for manual rescheduling.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "spots_remaining": { "description": "Unfilled winner capacity: `accepted_submissions_limit` minus `accepted_submissions_count`, clamped to zero. Not on its own a signal that the bounty accepts new claims — read `status` for that: only an `open` bounty takes new submissions.", "example": 1, "type": "integer" }, "status": { "description": "Lifecycle state. `scheduled` bounties are unpublished drafts, visible to their poster and the account's authorized managers; `open` bounties accept new submissions; `closed` bounties are live but no longer accept new submissions; `completed` bounties paid out every winner slot; `canceled` bounties ended before filling their slots.", "enum": [ "scheduled", "open", "closed", "completed", "canceled" ], "example": "open", "type": "string" }, "submissions_closed_at": { "description": "When new submissions stopped being accepted, as an ISO 8601 timestamp. Set when a cancellation is requested on a bounty with work in flight, so in-flight submissions can resolve before the bounty cancels. `null` when submissions were never stopped — including completed bounties that simply filled every winner slot.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "title": { "description": "Short name of the task shown to workers.", "example": "Photograph the storefront", "type": "string" }, "unresolved_submissions_count": { "description": "Submissions still awaiting an outcome: in progress or pending review.", "example": 1, "type": "integer" }, "updated_at": { "description": "When the bounty was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewer_accepted_submissions_count": { "description": "How many winner slots the authenticated user has already won on this bounty. Read against `accepted_submissions_per_user_limit` to show a worker their remaining allowance. `0` when the request has no authenticated user.", "example": 0, "type": "integer" } }, "required": [ "id", "title", "description", "status", "currency", "gross_reward_amount", "net_reward_amount", "affiliate_share_amount", "budget_amount", "gross_paid_out_amount", "accepted_submissions_limit", "accepted_submissions_per_user_limit", "accepted_submissions_count", "unresolved_submissions_count", "viewer_accepted_submissions_count", "spots_remaining", "business_goal_type", "accepted_deliverable_types", "min_total_verified_duration_seconds", "allowed_country_codes", "submissions_closed_at", "cancel_requested_at", "scheduled_publish_at", "scheduled_frequency", "experience_id", "discussion_post_id", "discussion_feed_id", "discussion_experience_id", "created_at", "updated_at", "poster", "funding_account", "hosting_account" ], "type": "object" }, "BountySubmission": { "properties": { "bounty_id": { "description": "The bounty the work was submitted to, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "capture_clips": { "items": { "$ref": "#/components/schemas/BountyCaptureClip", "description": "The submission's capture clips in recording order, each carrying its own review `status` and temporary signed artifact URLs. The full deliverable when `deliverable_type` is `data_capture`, populated only on single-submission reads; `null` on list responses (use `captured_clip_count` and `captured_duration_seconds` for the summary) and for other deliverable types. An attempt still in progress lists every clip it has recorded, including failed ones; once submitted, only clips that passed validation are listed, since only those are evidence." }, "type": [ "array", "null" ] }, "capture_filename": { "description": "The vendor filename stem `Country_City_Site_Station_Operator`, derived from the capture metadata. `null` until every component is present.", "example": "US_Austin_BurnetRd_Bay2_mwebb", "type": [ "string", "null" ] }, "captured_clip_count": { "description": "Number of verified capture clips accepted for this submission so far. `0` for submissions whose deliverable doesn't accumulate clips.", "example": 0, "type": "integer" }, "captured_duration_seconds": { "description": "Total verified duration of accepted capture clips, in whole seconds. `0` for submissions whose deliverable doesn't accumulate clips.", "example": 0, "type": "integer" }, "city": { "description": "Capture metadata: city the footage was recorded in. `null` unless capture metadata was provided.", "example": "Austin", "type": [ "string", "null" ] }, "claimed_at": { "description": "When the worker claimed the submission, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "content": { "description": "Written proof the worker submitted with their work.", "example": "Ceramic coating reveal, shot at the Burnet Rd bay", "type": [ "string", "null" ] }, "country": { "description": "Capture metadata: country the footage was recorded in. `null` unless capture metadata was provided.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the submission was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "deliverable_type": { "description": "How the work arrived when it came in through the API in one shot, informational only — read the work from `deliverable_urls`, `files`, and `capture_clips` directly. `null` for submissions whose proof is a livestream recording, including ones that attached links or files on submit.", "enum": [ "content_url", "media", "data_capture", null ], "example": "media", "type": [ "string", "null" ] }, "deliverable_urls": { "items": { "description": "Links submitted as work, followed by temporary download URLs for the uploaded files. `null` when the submission carries neither.", "example": "https://tiktok.com/@shinetime/video/1", "type": "string" }, "type": [ "array", "null" ] }, "denial_reason": { "description": "Why the submission was denied, when a presentable reason exists. Always `null` unless `status` is `denied`.", "example": "The clip never shows the finished paint.", "type": [ "string", "null" ] }, "device": { "description": "Capture metadata: device the footage was recorded on. `null` unless capture metadata was provided.", "example": "iPhone 15 Pro", "type": [ "string", "null" ] }, "files": { "items": { "$ref": "#/components/schemas/BountySubmissionFile", "description": "Files uploaded as part of the work, in upload order. Empty when the submission has none." }, "type": "array" }, "fov": { "description": "Capture metadata: horizontal field of view in degrees. `null` when not reported.", "example": 120, "type": [ "integer", "null" ] }, "id": { "description": "Submission ID, prefixed `btys_`.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" }, "latest_proof_livestream_feed": { "description": "Latest public proof livestream attached to the submission.", "oneOf": [ { "$ref": "#/components/schemas/BountySubmissionLivestreamFeed" }, { "type": "null" } ] }, "operator": { "description": "Capture metadata: identifier of the person who recorded the footage. `null` unless capture metadata was provided.", "example": "mwebb", "type": [ "string", "null" ] }, "resolved_at": { "description": "When the submission was approved or denied, as an ISO 8601 timestamp. `null` until then.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "site": { "description": "Capture metadata: site or venue the footage was recorded at. `null` unless capture metadata was provided.", "example": "BurnetRd", "type": [ "string", "null" ] }, "station": { "description": "Capture metadata: station or position within the site. `null` unless capture metadata was provided.", "example": "Bay2", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle state. `in_progress` submissions are active attempts that have not submitted proof yet; `submitted` submissions await review; `approved` submissions were accepted and paid; `denied` submissions were rejected. `null` when the attempt ended without proof, taking it out of the public lifecycle — those attempts are absent from every public list and read.", "enum": [ "in_progress", "submitted", "approved", "denied", null ], "example": "submitted", "type": [ "string", "null" ] }, "submitted_at": { "description": "When proof was submitted for review, as an ISO 8601 timestamp. `null` while the attempt is in progress.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "updated_at": { "description": "When the submission was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "worker": { "$ref": "#/components/schemas/UserSummary", "description": "User who submitted the work." } }, "required": [ "id", "bounty_id", "status", "deliverable_type", "deliverable_urls", "files", "captured_clip_count", "captured_duration_seconds", "capture_clips", "content", "denial_reason", "claimed_at", "submitted_at", "resolved_at", "country", "city", "site", "station", "operator", "device", "fov", "capture_filename", "created_at", "updated_at", "latest_proof_livestream_feed", "worker" ], "type": "object" }, "BountySubmissionFile": { "properties": { "attachment_type": { "description": "Broad kind of file.", "enum": [ "image", "video", "audio", "other", null ], "example": "image", "type": [ "string", "null" ] }, "content_type": { "description": "MIME type of the file.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "Name the file was uploaded with.", "example": "ceramic-coating-cut.png", "type": [ "string", "null" ] }, "id": { "description": "File ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "Temporary download URL for the file.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "url", "filename", "content_type", "attachment_type" ], "type": "object" }, "BountySubmissionLivestreamFeed": { "properties": { "ended_at": { "description": "When the proof livestream ended, as an ISO 8601 timestamp. `null` while it is still live — a feed with a `started_at` and no `ended_at` is streaming right now.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Livestream feed ID.", "example": "lfeed_3", "type": "string" }, "recording_status": { "description": "Recording lifecycle state.", "enum": [ "recording", "processing", "completed", "failed", null ], "example": "completed", "type": [ "string", "null" ] }, "recording_url": { "description": "Playback URL for a completed proof recording, when available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/video/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "started_at": { "description": "When the proof livestream went live, as an ISO 8601 timestamp. `null` before it starts.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Current proof thumbnail URL, when available.", "example": "https://img.whop.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxx/resize:fit/width:1000/height:500/plain/https://cdn.whop.com/livestreams/paint-correction-proof-cover.jpg", "type": [ "string", "null" ] }, "title": { "description": "Display title for the proof livestream.", "example": "Untitled Livestream", "type": "string" } }, "required": [ "id", "title", "started_at", "ended_at", "thumbnail_url", "recording_status", "recording_url" ], "type": "object" }, "BountyTypes": { "description": "The available bounty implementation types.", "enum": [ "classic", "user_funded", "workforce" ], "type": "string" }, "BusinessGoalTypes": { "description": "What the poster is trying to accomplish with a workforce bounty. Used for product taxonomy and analytics, separate from the bounty's implementation type.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "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" }, "CancelationStatus": { "description": "The state of a membership after a customer provides a cancelation reason.", "enum": [ "won_back", "left", "canceling" ], "type": "string" }, "CaptureSpec": { "properties": { "filename_pattern": { "description": "The naming convention for uploaded files, built from the required metadata fields.", "example": "Country_City_Site_Station_Operator", "type": "string" }, "imu": { "$ref": "#/components/schemas/CaptureSpecImu", "description": "Inertial measurement unit (IMU) recording requirements." }, "manifest_schema_version": { "description": "Schema version the client must stamp on the capture manifest it uploads.", "example": 2, "type": "integer" }, "min_clip_duration_seconds": { "description": "Minimum length of a single clip, in seconds.", "example": 120, "type": "integer" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate across all its clips before it can be submitted, in seconds. Always a whole number of hours.", "example": 14400, "type": "integer" }, "required_metadata_fields": { "items": { "description": "Metadata fields a submission must provide, matching the `metadata` object on the submissions API.", "example": "country", "type": "string" }, "type": "array" }, "single_continuous_take": { "description": "Whether each clip must be one uninterrupted recording rather than stitched segments.", "example": true, "type": "boolean" }, "video": { "$ref": "#/components/schemas/CaptureSpecVideo", "description": "Video recording requirements." } }, "required": [ "manifest_schema_version", "video", "imu", "min_clip_duration_seconds", "min_total_verified_duration_seconds", "single_continuous_take", "required_metadata_fields", "filename_pattern" ], "type": "object" }, "CaptureSpecImu": { "properties": { "device_motion_units": { "description": "Units for the device-motion channels, as a compact key=unit string.", "example": "ua=m/s²,gv=g,r=rad/s,q=unit", "type": "string" }, "magnetometer_units": { "description": "Units for the magnetometer channel.", "example": "µT", "type": "string" }, "min_rate_hz": { "description": "Minimum sustained IMU sample rate in hertz for a clip to pass validation.", "example": 90.0, "type": "number" }, "target_rate_hz": { "description": "Target IMU sample rate in hertz.", "example": 100, "type": "integer" }, "warmup_min_rate_hz": { "description": "Minimum IMU sample rate in hertz tolerated during the warmup window.", "example": 45.0, "type": "number" }, "warmup_ns": { "description": "Startup window, in nanoseconds, during which the relaxed warmup rate applies.", "example": 3000000000, "type": "integer" } }, "required": [ "target_rate_hz", "min_rate_hz", "warmup_ns", "warmup_min_rate_hz", "device_motion_units", "magnetometer_units" ], "type": "object" }, "CaptureSpecVideo": { "properties": { "bitrate_ceiling_mbps": { "description": "Maximum acceptable average bitrate, in megabits per second.", "example": 50, "type": "integer" }, "bitrate_floor_mbps": { "description": "Minimum acceptable average bitrate, in megabits per second.", "example": 4, "type": "integer" }, "bitrate_target_mbps": { "description": "Recommended average bitrate to encode at, in megabits per second.", "example": 12, "type": "integer" }, "camera_lens": { "description": "Which physical lens to record with.", "example": "ultra_wide", "type": "string" }, "codecs": { "items": { "description": "Accepted video codecs, in preference order.", "example": "h264", "type": "string" }, "type": "array" }, "embed_camera_metadata": { "description": "Whether the client must also write the camera make and model into the video container's metadata. When `false`, the capture manifest and export CSV are the metadata carrier.", "example": false, "type": "boolean" }, "fps": { "description": "Target capture frame rate.", "example": 30, "type": "integer" }, "frame_gap_tolerance_ms": { "description": "Longest stall between consecutive frames a clip may contain before the client rejects it, in milliseconds. Every frame is timestamped in the frame log, so a stall stays alignable downstream — this bounds how broken a capture may be, not how evenly it must be paced.", "example": 1000, "type": "integer" }, "height": { "description": "Required frame height in pixels — recorded footage must match exactly.", "example": 1080, "type": "integer" }, "min_fov_degrees": { "description": "Minimum acceptable horizontal field of view, in degrees.", "example": 130, "type": "integer" }, "orientation": { "description": "Device orientation to record in.", "example": "landscapeRight", "type": "string" }, "preferred_fov_degrees": { "description": "Preferred horizontal field of view, in degrees.", "example": 140, "type": "integer" }, "stabilization_mode": { "description": "How the client must configure video stabilization: `off` disables EIS so raw motion is preserved for pose extraction, `on` requires it, `any` leaves the device default.", "enum": [ "off", "on", "any" ], "example": "off", "type": "string" }, "stabilization_required": { "description": "Whether hardware/software stabilization must be enabled. True exactly when stabilization_mode is `on`.", "example": false, "type": "boolean" }, "width": { "description": "Required frame width in pixels — recorded footage must match exactly.", "example": 1920, "type": "integer" } }, "required": [ "codecs", "width", "height", "fps", "bitrate_floor_mbps", "bitrate_ceiling_mbps", "bitrate_target_mbps", "min_fov_degrees", "preferred_fov_degrees", "camera_lens", "orientation", "stabilization_required", "stabilization_mode", "embed_camera_metadata", "frame_gap_tolerance_ms" ], "type": "object" }, "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", "aura", "accel", "culiance", "nyce", "pulse", "star", "unknown" ], "type": "string" }, "CardFundingTypes": { "description": "The funding types of a card", "enum": [ "credit", "debit", "prepaid" ], "type": "string" }, "CardIssuingTransactionStatus": { "description": "The lifecycle status of a card transaction.", "enum": [ "pending", "completed", "reversed", "declined" ], "type": "string" }, "CardTransaction": { "properties": { "card_id": { "description": "The card this transaction was charged to, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "cardholder_id": { "description": "The user the card is assigned to, prefixed `user_`. Null when the card has no assigned cardholder.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "cashback_usd_amount": { "description": "Cashback earned on this transaction as a USD amount. Zero for declined or ineligible transactions, and null when cashback has not been computed yet.", "example": 0.25, "type": [ "number", "null" ] }, "created_at": { "description": "When the transaction was authorized, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "ISO 4217 currency code the merchant charged in.", "example": "EUR", "type": [ "string", "null" ] }, "declined_reason": { "description": "Why the transaction was declined. Null unless `status` is `declined`.", "example": "account_credit_limit_exceeded", "type": [ "string", "null" ] }, "id": { "description": "Card transaction ID, prefixed `citx_`.", "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "international": { "description": "True when the merchant is outside the card's home country.", "example": true, "type": "boolean" }, "local_amount": { "description": "Amount the merchant charged in their own currency. Pair with `currency`.", "example": 22.5, "type": [ "number", "null" ] }, "merchant_category": { "description": "Merchant category label, enriched where available and otherwise as the card network reported it.", "example": "Car Care Supplies", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "Four-digit ISO 18245 merchant category code (MCC).", "example": "5533", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "URL of the enriched merchant logo. Null when no logo was matched.", "example": "https://shinetime.example/icons/lone-star-detail-supply.png", "type": [ "string", "null" ] }, "merchant_name": { "description": "Merchant name, enriched where available and otherwise as the card network reported it.", "example": "Lone Star Detail Supply", "type": [ "string", "null" ] }, "posted_at": { "description": "When the card network settled the transaction, as an ISO 8601 timestamp. Null until it settles.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Current status of the transaction.", "enum": [ "pending", "completed", "reversed", "declined" ], "example": "completed", "type": "string" }, "transaction_type": { "description": "The kind of card transaction. Always `spend` today.", "enum": [ "spend" ], "example": "spend", "type": "string" }, "usd_amount": { "description": "Amount charged in USD. Negative when the merchant refunded the card.", "example": 24.99, "type": [ "number", "null" ] } }, "required": [ "id", "card_id", "cardholder_id", "status", "transaction_type", "usd_amount", "local_amount", "currency", "international", "merchant_name", "merchant_icon_url", "merchant_category", "merchant_category_code", "declined_reason", "cashback_usd_amount", "created_at", "posted_at" ], "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": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "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", null ], "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the plan's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutSessionPaymentMethodConfiguration" }, { "type": "null" } ] }, "id": { "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the plan or platform defaults.", "type": [ "object", "null" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutConfigurationPlan" }, { "type": "null" } ] }, "purchase_url": { "description": "Checkout URL you can send to customers.", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "type": [ "string", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode", "currency", "plan", "affiliate_code", "metadata", "redirect_url", "purchase_url", "three_ds_level", "payment_method_configuration", "effective_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" ] }, "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": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "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": "Access duration in days for expiration-based plans, such as 365 for a one-year 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": "Sales method for 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": "Free trial days before first renewal charge. `null` if no trial is configured or the 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/ch_xxxx/`", "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", "payment_method_configuration" ], "type": "object" }, "CheckoutConfigurationPlan": { "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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" }, "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" }, "CheckoutSessionPaymentMethodConfiguration": { "properties": { "disabled": { "items": { "description": "Payment methods this checkout withholds, even when the defaults would offer them.", "example": "card", "type": "string" }, "type": "array" }, "enabled": { "items": { "description": "Payment methods this checkout offers on top of whatever the defaults provide.", "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's default set is the starting point. When `false`, only `enabled` is offered.", "example": true, "type": "boolean" } }, "required": [ "enabled", "disabled", "include_platform_defaults" ], "type": "object" }, "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": "URL slug for the account'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": "URL slug for the account'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" }, "ConfirmationToken": { "properties": { "billing_details": { "description": "Enough of the billing details to raise a customer record and recognise the method — email, name, country and postal code. The street address is collected for the charge but never returned; this endpoint is a display-safe preview.", "oneOf": [ { "$ref": "#/components/schemas/PaymentBillingDetailsPreview" }, { "type": "null" } ] }, "created_at": { "description": "When the token was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "expires_at": { "description": "When the token expires, as an ISO 8601 timestamp. Tokens are single-use and short-lived.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "example": "ctok_xxxxxxxxxxxxxx", "type": "string" }, "object": { "description": "Always `confirmation_token`.", "example": "confirmation_token", "type": "string" }, "payment_method_preview": { "$ref": "#/components/schemas/PaymentMethodDisplay", "description": "Display-only preview of the collected method — never the underlying token." }, "setup_future_usage": { "description": "Save-consent state the element displayed at collection: `off_session`, `on_session`, or `null`. Confirm may vault only if attested here.", "example": "off_session", "type": [ "string", "null" ] }, "status": { "description": "`pending` until it is used, then `consumed`; `expired` once its short lifetime elapses. Only a `pending` token can be charged.", "enum": [ "pending", "consumed", "expired" ], "example": "pending", "type": "string" } }, "required": [ "id", "object", "status", "payment_method_preview", "setup_future_usage", "billing_details", "created_at", "expires_at" ], "type": "object" }, "ConversionEvent": { "anyOf": [ { "enum": [ "purchase", "add_to_cart", "initiated_checkout", "add_payment_info", "complete_registration", "lead", "content_view", "search", "contact", "customize_product", "donate", "find_location", "schedule", "start_trial", "submit_application", "subscribe" ], "example": "purchase", "type": "string" }, { "type": "string" }, { "type": "null" } ], "description": "The pixel event optimized for. A standard event, or any custom pixel event name." }, "Countries": { "description": "The available countries on the platform", "enum": [ "us", "ca", "gb", "ab", "af", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "ba", "bw", "br", "io", "vg", "bn", "bg", "bf", "bi", "kh", "cm", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "ck", "cr", "ci", "hr", "cu", "cw", "cy", "cz", "cd", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gg", "gn", "gw", "gy", "ht", "hn", "hk", "hu", "is", "in", "id", "iq", "ie", "im", "il", "it", "jm", "sj", "jp", "je", "jo", "kz", "ke", "ki", "xk", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "me", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "an", "nc", "nz", "ni", "ne", "ng", "nu", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "bl", "sh", "kn", "lc", "mf", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sx", "sk", "si", "sb", "so", "za", "kr", "ss", "es", "lk", "sd", "sr", "sz", "se", "ch", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "vi", "ug", "ua", "ae", "um", "uy", "uz", "vu", "va", "ve", "vn", "wf", "eh", "ye", "zm", "zw", "sy" ], "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" }, "chapters_count": { "description": "The total number of chapters in this course, including chapters whose lessons are all hidden from the current user.", "example": 42, "type": "integer" }, "completed_lessons_count": { "description": "The number of lessons in this course that the current user has marked as completed. Zero when the request is not made on behalf of a user.", "example": 42, "type": "integer" }, "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." }, "latest_lesson_created_at": { "description": "The creation timestamp of the most recently added lesson visible to the current user. Null if the course has no lessons.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "lesson_unlock_days": { "description": "The distinct drip schedules, in days after the course start, of lessons visible to the current user. Combine with startedAt to work out which have unlocked. Empty when the user has not started the course or no lesson is on a schedule.", "items": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": "integer" }, "type": "array" }, "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" }, "resume_lesson": { "description": "The lesson the current user should continue from: their first incomplete lesson, or the first lesson when they have finished the course, have not started it, or can edit it. Null if the course has no lessons.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "started_at": { "description": "The earliest time the current user is known to have started this course. Null if they have not started it. Drip unlock schedules are measured from this point.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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" ] }, "total_duration_seconds": { "description": "The combined duration in seconds of every hosted video across the lessons visible to the current user.", "example": 42, "type": "integer" }, "total_lessons_count": { "description": "The number of lessons in this course visible to the current user.", "example": 42, "type": "integer" }, "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_count", "total_lessons_count", "completed_lessons_count", "total_duration_seconds", "latest_lesson_created_at", "started_at", "lesson_unlock_days", "resume_lesson", "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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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" ] }, "chapters_count": { "description": "The total number of chapters in this course, including chapters whose lessons are all hidden from the current user.", "example": 42, "type": "integer" }, "completed_lessons_count": { "description": "The number of lessons in this course that the current user has marked as completed. Zero when the request is not made on behalf of a user.", "example": 42, "type": "integer" }, "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." }, "latest_lesson_created_at": { "description": "The creation timestamp of the most recently added lesson visible to the current user. Null if the course has no lessons.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "lesson_unlock_days": { "description": "The distinct drip schedules, in days after the course start, of lessons visible to the current user. Combine with startedAt to work out which have unlocked. Empty when the user has not started the course or no lesson is on a schedule.", "items": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": "integer" }, "type": "array" }, "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" }, "resume_lesson": { "description": "The lesson the current user should continue from: their first incomplete lesson, or the first lesson when they have finished the course, have not started it, or can edit it. Null if the course has no lessons.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "started_at": { "description": "The earliest time the current user is known to have started this course. Null if they have not started it. Drip unlock schedules are measured from this point.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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" ] }, "total_duration_seconds": { "description": "The combined duration in seconds of every hosted video across the lessons visible to the current user.", "example": 42, "type": "integer" }, "total_lessons_count": { "description": "The number of lessons in this course visible to the current user.", "example": 42, "type": "integer" }, "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_count", "total_lessons_count", "completed_lessons_count", "total_duration_seconds", "latest_lesson_created_at", "started_at", "lesson_unlock_days", "resume_lesson" ], "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" }, "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" }, "DetailedTargetingOption": { "properties": { "audience_size_lower_bound": { "description": "Low end of the ad platform's estimate of how many people this option can reach. Null when the platform doesn't publish one.", "example": 18400000, "type": [ "number", "null" ] }, "audience_size_upper_bound": { "description": "High end of the ad platform's estimate of how many people this option can reach. Null when the platform doesn't publish one.", "example": 21700000, "type": [ "number", "null" ] }, "behavior_type": { "description": "What a behavior category is measured on, on ad platforms that scope them. Send it back on the `detailed_targeting.behaviors` entry alongside the id. Null for options that aren't scoped.", "enum": [ "video", "creator", "hashtag", null ], "example": "video", "type": [ "string", "null" ] }, "description": { "description": "The ad platform's description of who the option covers, when it publishes one.", "example": "People who have expressed an interest in or like pages related to car washing and detailing.", "type": [ "string", "null" ] }, "id": { "description": "The ad platform's ID for the option in its targeting taxonomy. Use it as the `id` of a `detailed_targeting` entry.", "example": "6003193685204", "type": "string" }, "name": { "description": "Display name, such as `Movies`.", "example": "Car wash", "type": "string" }, "type": { "description": "Which detailed-targeting field the option belongs in: `interests` and `behaviors` go in the matching `detailed_targeting` field; demographic categories (`life_events`, `industries`, `income`, `family_statuses`, `work_employers`, `work_positions`, `education_schools`, `education_majors`) go in `detailed_targeting.demographics` with this value as the entry's `type`.", "enum": [ "interests", "behaviors", "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors" ], "example": "interests", "type": "string" } }, "required": [ "type", "id", "name", "behavior_type", "audience_size_lower_bound", "audience_size_upper_bound", "description" ], "title": "Detailed targeting", "type": "object" }, "Direction": { "description": "The direction of the sort.", "enum": [ "asc", "desc" ], "type": "string" }, "Dispute": { "properties": { "account_id": { "description": "The account the dispute was filed against, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "The disputed amount, in whole units of `currency`.", "example": 150.0, "type": "number" }, "buyer": { "description": "The customer who filed the dispute.", "oneOf": [ { "$ref": "#/components/schemas/DisputeBuyer" }, { "type": "null" } ] }, "created_at": { "description": "When the dispute was opened, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the disputed amount.", "example": "usd", "type": "string" }, "evidence": { "$ref": "#/components/schemas/DisputeEvidence", "description": "The evidence packet sent to the processor to contest the dispute." }, "evidence_due_at": { "description": "The deadline to submit evidence, as an ISO 8601 timestamp. Whop reserves the last 24 hours before the processor's own cutoff to forward the submission.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "evidence_editable": { "description": "Whether `evidence` can still be changed and submitted.", "example": false, "type": "boolean" }, "evidence_locked_reason": { "description": "Why evidence can no longer be edited. `null` while `evidence_editable` is true.", "enum": [ "submitted", "response_window_closed", "not_contestable", null ], "example": "submitted", "type": [ "string", "null" ] }, "evidence_submitted_at": { "description": "When the evidence was submitted to the processor, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "generated_response_attachment": { "description": "The AI-generated representment document filed with the processor on the seller's behalf, once ready. Null until generation completes, and for disputes not using Whop Dispute Fighter.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "id": { "description": "Dispute ID, prefixed `dspt_`.", "example": "dspt_xxxxxxxxxxxxxx", "type": "string" }, "inquiry": { "description": "Whether this is a pre-dispute inquiry rather than a formal chargeback. Inquiries follow the same lifecycle but move no funds unless one escalates.", "example": false, "type": "boolean" }, "issuer_comments": { "items": { "$ref": "#/components/schemas/DisputeIssuerComment", "description": "What the card issuer said when filing the dispute. Only populated when the issuer provides them, and listed in the order they were received." }, "type": "array" }, "payment": { "description": "The payment being disputed.", "oneOf": [ { "$ref": "#/components/schemas/DisputePayment" }, { "type": "null" } ] }, "plan_id": { "description": "The plan the disputed payment was made on, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the disputed payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "rapid_dispute_resolution": { "description": "Whether Visa Rapid Dispute Resolution settled this automatically. These refund the customer without an evidence round.", "example": false, "type": "boolean" }, "reason": { "description": "Why the customer says they are disputing, normalized across card networks. `other` covers a code Whop has not categorized yet — read `reason_code` for the raw value.", "enum": [ "fraudulent", "unrecognized", "declined_authorization", "product_not_received", "product_unacceptable", "subscription_canceled", "credit_not_processed", "duplicate", "processing_error", "documentation_request", "bank_cannot_process", "other" ], "example": "other", "type": "string" }, "reason_code": { "description": "The raw card-network or processor reason code, such as `10.4`.", "example": "13.1", "type": [ "string", "null" ] }, "status": { "description": "Where the dispute stands. `needs_response` is awaiting evidence, `under_review` is with the processor, `won` returned the funds to the seller, `lost` returned them to the customer, and `closed` ended without a ruling. A dispute past its `evidence_due_at` reports `under_review` — the window to respond has closed.", "enum": [ "needs_response", "under_review", "won", "lost", "closed" ], "example": "under_review", "type": "string" }, "updated_at": { "description": "When the dispute was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "status", "inquiry", "amount", "currency", "reason", "reason_code", "issuer_comments", "account_id", "product_id", "plan_id", "rapid_dispute_resolution", "evidence_editable", "evidence_locked_reason", "evidence_due_at", "evidence_submitted_at", "buyer", "payment", "evidence", "generated_response_attachment", "created_at", "updated_at" ], "type": "object" }, "DisputeAlert": { "properties": { "account_id": { "description": "The account the alerted payment belongs to, prefixed `biz_`. `null` while the alert is unmatched.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "actionable": { "description": "Whether refunding the payment can still avoid a chargeback. `false` once the payment has been disputed or fully refunded, or when the alert could not be matched to a payment — `not_actionable_reason` says which.", "example": false, "type": "boolean" }, "amount": { "description": "The alerted amount, in whole units of `currency`. This is what the issuer reported, which can differ from the payment's own amount.", "example": 25.0, "type": "number" }, "card_brand": { "description": "The card network as reported by the issuer, lowercased, such as `visa` or `mastercard`. `unknown` when the report carries neither a network nor a recognizable BIN.", "example": "visa", "type": [ "string", "null" ] }, "created_at": { "description": "When Whop received the alert, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the alerted amount.", "example": "usd", "type": "string" }, "fee_charged": { "description": "Whether Whop charged the account an alert fee for this one. Always `false` for `early_fraud_warning`, which Whop is not billed for and never passes on.", "example": false, "type": "boolean" }, "id": { "description": "Dispute alert ID, prefixed `dspa_`.", "example": "dspa_xxxxxxxxxxxxxx", "type": "string" }, "issuer": { "description": "Name of the bank that issued the card and filed the report.", "type": [ "string", "null" ] }, "not_actionable_reason": { "description": "Why refunding can no longer avoid a chargeback. `network_resolved` when a Visa RDR already closed the case, `payment_unmatched` when no payment matched, `payment_not_captured` when it never captured money, `payment_disputed` once the payment carries a dispute, `payment_refunded` once fully refunded. `null` while `actionable` is true.", "enum": [ "network_resolved", "payment_unmatched", "payment_not_captured", "payment_disputed", "payment_refunded", null ], "example": "network_resolved", "type": [ "string", "null" ] }, "payment_id": { "description": "The payment the issuer reported, prefixed `pay_`. `null` when Whop could not match the report to a payment.", "example": "pay_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the alerted payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "reported_at": { "description": "When the issuer filed the report, as an ISO 8601 timestamp. Earlier than `created_at`, which is when Whop received it.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "transaction_at": { "description": "When the reported transaction was made, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "type": { "description": "What the issuer sent. `early_fraud_warning` is a fraud report on a settled payment (Visa TC40 / Mastercard SAFE) — refunding still avoids the chargeback, and Whop never charges a fee for one. `dispute_alert` is a pre-dispute notice from the issuer's alert network, which Whop pays for and passes on as a fee. `rapid_dispute_resolution` is a Visa RDR case the network already closed by refunding the payment — nothing is left to act on.", "enum": [ "early_fraud_warning", "dispute_alert", "rapid_dispute_resolution" ], "example": "rapid_dispute_resolution", "type": "string" }, "updated_at": { "description": "When the alert was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "type", "actionable", "not_actionable_reason", "amount", "currency", "card_brand", "issuer", "account_id", "payment_id", "product_id", "fee_charged", "reported_at", "transaction_at", "created_at", "updated_at" ], "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" }, "DisputeAttachment": { "properties": { "content_type": { "description": "The uploaded file's MIME type.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "The uploaded file's name.", "example": "booking-confirmation-email.png", "type": [ "string", "null" ] }, "id": { "description": "The attachment's ID. `null` for a Whop-hosted policy, which is not an uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "platform": { "description": "Whether this is Whop's own hosted policy, standing in because the seller uploaded none. Sending it back on a PATCH changes nothing.", "example": false, "type": "boolean" }, "url": { "description": "A URL to download the attachment.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url", "platform" ], "type": "object" }, "DisputeBuyer": { "properties": { "email": { "description": "The customer's email address. Requires the `member:email:read` scope; `null` without it.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "member_id": { "description": "The customer's member row on the account, prefixed `mem_`.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "name": { "description": "The customer's display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "user_id": { "description": "The customer's user ID, prefixed `user_`. `null` for a guest checkout.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "The customer's Whop username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "user_id", "member_id", "name", "username", "email" ], "type": "object" }, "DisputeEvidence": { "properties": { "access_activity_log": { "description": "Log of the customer's access to the product, such as sign-in or download activity.", "example": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address the customer provided at checkout.", "example": "4180 Burnet Rd, Austin, TX 78756, US", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document. Falls back to Whop's platform policy when the seller has not uploaded their own.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "cancellation_policy_disclosure": { "description": "How the cancellation policy was shown to the customer before purchase.", "example": "Shown at checkout and again in the booking confirmation email.", "type": [ "string", "null" ] }, "customer_communication_attachment": { "description": "Correspondence with the customer, or proof they used the product.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "customer_email_address": { "description": "The email address the customer used at checkout.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's name as given at checkout.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "documents": { "items": { "$ref": "#/components/schemas/DisputeEvidenceDocument", "description": "Additional evidence documents uploaded through `POST /disputes/{id}/upload_evidence`, beyond the four fixed slots. Each rides into the submitted packet under its `document_type`." }, "type": "array" }, "notes": { "description": "Any additional context for the processor reviewing the dispute.", "example": "Two-day ceramic coating completed and collected. Before and after photos attached.", "type": [ "string", "null" ] }, "product_description": { "description": "What the customer purchased, in the seller's own words.", "example": "Two-stage paint correction with a three-year ceramic coating.", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document. Falls back to Whop's platform policy when the seller has not uploaded their own.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "refund_policy_disclosure": { "description": "How the refund policy was shown to the customer before purchase.", "example": "Linked from the booking page and accepted at checkout.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "Why a refund was refused, when one was requested and denied.", "example": "Work was completed and the vehicle collected, so the deposit is non-refundable.", "type": [ "string", "null" ] }, "service_date": { "description": "When the product or service was delivered.", "example": "2026-01-01", "type": [ "string", "null" ] }, "uncategorized_attachment": { "description": "Supporting evidence that does not fit the other categories.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] } }, "required": [ "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", "documents" ], "type": "object" }, "DisputeEvidenceDocument": { "properties": { "content_type": { "description": "The uploaded file's MIME type. Uploads are restricted to the types the processor accepts.", "enum": [ "application/pdf", "application/json", "image/jpeg", "image/png", "image/webp", null ], "example": "image/png", "type": [ "string", "null" ] }, "created_at": { "description": "When the file was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "document_type": { "description": "What kind of evidence the document is.", "enum": [ "return_policy", "shipping_policy", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription" ], "example": "customer_order_history", "type": "string" }, "filename": { "description": "The original filename, including its extension.", "example": "customer-order-history.png", "type": [ "string", "null" ] }, "id": { "description": "The file's ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "multipart_chunk_size": { "description": "The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.", "type": [ "integer", "null" ] }, "multipart_upload_id": { "description": "The ID of the multipart upload, passed back to `complete`. Present only on create, and only for multipart uploads.", "type": [ "string", "null" ] }, "multipart_upload_urls": { "items": { "$ref": "#/components/schemas/FileMultipartUrl", "description": "The presigned URL for each part. Present only on create, and only for multipart uploads." }, "type": [ "array", "null" ] }, "object": { "description": "The type of this object, always `file`.", "example": "file", "type": "string" }, "size": { "description": "The file size in bytes. `null` until the upload has finished.", "example": 1024, "type": [ "integer", "null" ] }, "upload_headers": { "description": "Headers to send with the upload PUT. Present only on create.", "type": "object" }, "upload_status": { "description": "Where the file is in its upload lifecycle.", "enum": [ "pending", "processing", "ready", "failed" ], "example": "ready", "type": "string" }, "upload_url": { "description": "Presigned URL to PUT the file's bytes to. Present only on create, and only for single-part uploads.", "type": [ "string", "null" ] }, "url": { "description": "A URL to download the file: a permanent CDN URL for public files, a signed expiring URL for private ones. `null` until the upload has finished.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "visibility": { "description": "`public` files are served via an unsigned CDN URL; `private` files via a signed, expiring URL.", "enum": [ "public", "private" ], "example": "public", "type": "string" } }, "required": [ "object", "id", "filename", "content_type", "size", "url", "upload_status", "visibility", "created_at", "document_type" ], "type": "object" }, "DisputeIssuerComment": { "properties": { "received_at": { "description": "When the comment was received, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "text": { "description": "What the issuer wrote, as received.", "example": "Note: Cardholder states the ceramic coating appointment never took place\nCancellation method: By phone", "type": "string" } }, "required": [ "received_at", "text" ], "type": "object" }, "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" }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "icons" ], "type": [ "object", "null" ] } }, "required": [ "id", "payment_instrument" ], "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" ] }, "reason_code": { "description": "The card network reason code for the dispute. Null when the payment processor did not provide one.", "example": "10.4", "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", "reason_code", "plan", "product", "company", "payment" ], "type": "object" }, "DisputePayment": { "properties": { "amount": { "description": "What the customer was charged, in whole units of the payment's currency.", "example": 249.0, "type": [ "number", "null" ] }, "card_brand": { "description": "Card brand, when the customer paid by card.", "example": "visa", "type": [ "string", "null" ] }, "card_last4": { "description": "Last four digits of the card, when the customer paid by card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was made, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the payment. Can differ from the dispute's currency when the processor settles in another currency.", "example": "usd", "type": [ "string", "null" ] }, "id": { "description": "Payment ID, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the payment names no method.", "oneOf": [ { "$ref": "#/components/schemas/PaymentInstrument" }, { "type": "null" } ] }, "payment_method_type": { "description": "How the customer paid, such as `card` or `paypal`.", "example": "card", "type": [ "string", "null" ] }, "payment_processor": { "description": "The processor that handled the payment, such as `stripe`.", "example": "stripe", "type": [ "string", "null" ] } }, "required": [ "id", "amount", "currency", "payment_method_type", "payment_processor", "card_brand", "card_last4", "payment_instrument", "created_at" ], "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" }, "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": "URL slug for the account'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": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "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": "URL slug for the account'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" }, "ExperienceNotificationPreference": { "properties": { "level": { "description": "What the user is notified about in the experience: `all` notifications, only `mentions`, or `nothing`.", "enum": [ "all", "mentions", "nothing" ], "example": "all", "type": "string" }, "object": { "description": "The type of object. Always `experience_notification_preference`.", "enum": [ "experience_notification_preference" ], "example": "experience_notification_preference", "type": "string" }, "scope": { "$ref": "#/components/schemas/NotificationPreferenceScope", "description": "What the preference applies to. Echo it back to `PATCH /users/me/preferences/notifications` to change this preference." } }, "required": [ "object", "scope", "level" ], "type": "object" }, "Export": { "properties": { "created_at": { "description": "When the export was requested, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "download_url": { "description": "A short-lived link to download the finished file. `null` until `status` is `completed`, and again once the export has expired.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "expires_at": { "description": "When the file is deleted and the export moves to `expired`, as an ISO 8601 timestamp. Exports are retained for 30 days.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Export ID, prefixed `exprt_`.", "example": "exprt_xxxxxxxxxxxxxx", "type": "string" }, "progress_percent": { "description": "Estimated completion percentage from 0 to 100.", "example": 0, "type": [ "integer", "null" ] }, "resource": { "description": "The resource that was exported, e.g. `receipts`, `members`, or `payouts`.", "enum": [ "ad_campaigns", "ad_groups", "ads", "apps", "audiences", "bounties", "bounty_submissions", "card_transactions", "checkout_configurations", "disputes", "events", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "content_rewards_submissions", "invoices", "cancelation_reasons", "child_companies", "ledger_lines", "withdrawal_lines" ], "example": "members", "type": "string" }, "status": { "description": "`pending` or `processing` while the file is generated, `completed` when the download is ready, `failed` if it errored, `expired` once the file has been deleted.", "enum": [ "pending", "processing", "completed", "failed", "expired" ], "example": "completed", "type": "string" }, "updated_at": { "description": "When the export last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "resource", "status", "progress_percent", "download_url", "expires_at", "created_at", "updated_at" ], "type": "object" }, "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": { "properties": { "content_type": { "description": "The file's MIME type, e.g. `application/pdf`.", "example": "application/pdf", "type": [ "string", "null" ] }, "created_at": { "description": "When the file was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "filename": { "description": "The original filename, including its extension.", "example": "evidence.pdf", "type": [ "string", "null" ] }, "id": { "description": "The file's ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "multipart_chunk_size": { "description": "The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.", "example": 5242880, "type": [ "integer", "null" ] }, "multipart_upload_id": { "description": "The ID of the multipart upload, passed back to `complete`. Present only on create, and only for multipart uploads.", "example": "upload-id", "type": [ "string", "null" ] }, "multipart_upload_urls": { "items": { "$ref": "#/components/schemas/FileMultipartUrl", "description": "The presigned URL for each part. Present only on create, and only for multipart uploads." }, "type": [ "array", "null" ] }, "object": { "description": "The type of this object, always `file`.", "example": "file", "type": "string" }, "size": { "description": "The file size in bytes. `null` until the upload has finished.", "example": 9670, "type": [ "integer", "null" ] }, "upload_headers": { "description": "Headers to send with the upload PUT. Present only on create.", "example": {}, "type": "object" }, "upload_status": { "description": "Where the file is in its upload lifecycle.", "enum": [ "pending", "processing", "ready", "failed" ], "example": "pending", "type": "string" }, "upload_url": { "description": "Presigned URL to PUT the file's bytes to. Present only on create, and only for single-part uploads.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf", "type": [ "string", "null" ] }, "url": { "description": "A URL to download the file: a permanent CDN URL for public files, a signed expiring URL for private ones. `null` until the upload has finished.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/audio/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "visibility": { "description": "`public` files are served via an unsigned CDN URL; `private` files via a signed, expiring URL.", "enum": [ "public", "private" ], "example": "private", "type": "string" } }, "required": [ "object", "id", "filename", "content_type", "size", "url", "upload_status", "visibility", "created_at" ], "type": "object" }, "FileMultipartUrl": { "properties": { "part_number": { "description": "The 1-based index of this part within the multipart upload.", "example": 1, "type": "integer" }, "url": { "description": "The presigned URL to PUT this part's bytes to.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf", "type": "string" } }, "required": [ "part_number", "url" ], "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" }, "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" } }, "required": [ "id", "name", "is_public" ], "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" }, "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" } }, "required": [ "id", "name", "is_public" ], "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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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", "requires_capture", "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" }, "FutureUsageTypes": { "description": "How a payment method will be charged after the buyer leaves — the same vocabulary as a confirmation token's setup_future_usage.", "enum": [ "off_session", "on_session" ], "type": "string" }, "GlobalAffiliateStatuses": { "description": "The different statuses of the global affiliate program for a product.", "enum": [ "enabled", "disabled" ], "type": "string" }, "GrantableAuthorizedUserRoles": { "description": "System roles accepted by legacy authorized-user mutations", "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser" ], "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-2 country code reported by the identity provider, such as `US` or `GB`. For individuals this is the country of citizenship or residence; for businesses, 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" }, "payout_status": { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses", "description": "Progress of payout-account setup for this profile, independent of holds. `connected` means onboarding is complete; a `connected` status paired with `payouts_enabled: false` indicates an active account restriction rather than incomplete setup." }, "payouts_enabled": { "description": "Whether this profile can receive payouts right now. True only when payout onboarding is complete and no payout holds are active on the linked account. Treat this as the single source of truth for payout readiness.", "type": "boolean" }, "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. Returns `action_required` whenever the profile has an open request for information (whether a verification, payout, or audit RFI) — i.e. the merchant must submit something before it is in good standing." }, "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", "payout_status", "payouts_enabled", "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-2 country code reported by the identity provider, such as `US` or `GB`. For individuals this is the country of citizenship or residence; for businesses, 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" }, "payout_status": { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses", "description": "Progress of payout-account setup for this profile, independent of holds. `connected` means onboarding is complete; a `connected` status paired with `payouts_enabled: false` indicates an active account restriction rather than incomplete setup." }, "payouts_enabled": { "description": "Whether this profile can receive payouts right now. True only when payout onboarding is complete and no payout holds are active on the linked account. Treat this as the single source of truth for payout readiness.", "type": "boolean" }, "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. Returns `action_required` whenever the profile has an open request for information (whether a verification, payout, or audit RFI) — i.e. the merchant must submit something before it is in good standing." }, "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", "payout_status", "payouts_enabled", "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", "manual_review", "approved", "rejected", "action_required" ], "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": { "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" ] }, "charge_buyer_fee": { "description": "Whether the invoice includes a buyer processing fee on top of the plan price.", "type": "boolean" }, "collection_method": { "$ref": "#/components/schemas/InvoiceCollectionMethods", "description": "The method used to collect payment for this invoice, such as automatic charging or manual payment." }, "company": { "description": "The company that issued this invoice.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "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." }, "description": { "description": "A text description of the plan visible to customers. Maximum 1000 characters. Null if no description is set.", "example": "Monthly access to all premium analytics dashboards and data exports.", "type": [ "string", "null" ] }, "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", "description" ], "type": "object" }, "customer_name": { "description": "The full name of the customer this invoice is addressed to. Null if no name is on file.", "example": "Jane Doe", "type": [ "string", "null" ] }, "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" }, "line_items": { "description": "Optional line items that break down the invoice total into individual charges.", "items": { "description": "A line item on an invoice, representing a single charge with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "example": "Platform subscription", "type": "string" }, "position": { "description": "The display order of this line item within the invoice.", "example": 42, "type": "integer" }, "quantity": { "description": "The quantity of this line item.", "example": 6.9, "type": "number" }, "total": { "description": "The computed total for this line item (quantity * unit_price).", "example": 6.9, "type": "number" }, "unit_price": { "description": "The unit price for this line item. Negative for a credit or deduction.", "example": 6.9, "type": "number" } }, "required": [ "label", "quantity", "unit_price", "total", "position" ], "type": "object" }, "type": "array" }, "mailing_address": { "description": "The billing/mailing address associated with this invoice, if one was provided at creation time.", "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" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country", "phone" ], "type": [ "object", "null" ] }, "member": { "description": "The member that the invoice was created for. Null when the invoice is addressed to an email address with no member record behind it.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "pay_online_url": { "description": "The checkout URL where the customer can pay this invoice online, with their email address pre-filled and locked.", "type": [ "string", "null" ] }, "payment": { "description": "The payment that settled this invoice. Null while the invoice is unpaid, when the invoice was marked paid manually, and on a subscription renewal invoice, where the settling payment cannot yet be identified.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "payment_processing": { "description": "Whether a payment on this invoice is still clearing. True while a delayed payment method such as ACH or SEPA settles, during which the invoice stays open and is not marked past due.", "type": "boolean" }, "product": { "description": "The product that this invoice was generated 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" }, "status": { "$ref": "#/components/schemas/InvoiceStatuses", "description": "The current payment status of the invoice, such as draft, open, paid, or void." }, "subscription_billing_anchor_at": { "description": "The date that defines when the subscription billing cycle starts. When set on a renewal plan invoice, all future billing periods anchor to this date.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the invoice was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user this invoice is addressed to. Null if the user account has been removed.", "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", "created_at", "status", "payment_processing", "number", "due_date", "email_address", "fetch_invoice_token", "line_items", "updated_at", "company", "user", "member", "payment", "automatically_finalizes_at", "subscription_billing_anchor_at", "collection_method", "charge_buyer_fee", "customer_name", "pay_online_url", "current_plan", "product", "mailing_address" ], "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" }, "line_items": { "description": "Optional line items that break down the invoice total into individual charges.", "items": { "description": "A line item on an invoice, representing a single charge with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "example": "Platform subscription", "type": "string" }, "position": { "description": "The display order of this line item within the invoice.", "example": 42, "type": "integer" }, "quantity": { "description": "The quantity of this line item.", "example": 6.9, "type": "number" }, "total": { "description": "The computed total for this line item (quantity * unit_price).", "example": 6.9, "type": "number" }, "unit_price": { "description": "The unit price for this line item. Negative for a credit or deduction.", "example": 6.9, "type": "number" } }, "required": [ "label", "quantity", "unit_price", "total", "position" ], "type": "object" }, "type": "array" }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "payment_processing": { "description": "Whether a payment on this invoice is still clearing. True while a delayed payment method such as ACH or SEPA settles, during which the invoice stays open and is not marked past due.", "type": "boolean" }, "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", "payment_processing", "number", "due_date", "email_address", "fetch_invoice_token", "current_plan", "line_items", "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" }, "LanguageTargetingOption": { "properties": { "code": { "description": "ISO 639 code the ad-group `languages` field takes, such as `en`.", "example": "en", "type": "string" }, "name": { "description": "Display name, such as `English`.", "example": "English", "type": "string" }, "type": { "description": "Always `languages`. The option goes in the ad-group `languages` field.", "enum": [ "languages" ], "example": "languages", "type": "string" } }, "required": [ "type", "code", "name" ], "title": "Language", "type": "object" }, "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": "URL slug for the account'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 payout readiness state.", "oneOf": [ { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses" }, { "type": "null" } ] } }, "required": [ "id", "status", "business_name", "phone", "email", "business_representative", "address", "latest_verification" ], "type": [ "object", "null" ] }, "settlement_time_at": { "description": "The settlement batch most recently posted to this account's available balance, at midnight UTC. Every payment settling in that batch carries the same `settlement_time_at`.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "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", "settlement_time_at", "balances", "treasury_balance", "transfer_fee", "payout_account_details", "payments_approval_status", "ledger_type", "owner" ], "type": "object" }, "LedgerActivity": { "properties": { "account": { "description": "The viewer account that owns this row's ledger. Present only when the response aggregates owned accounts (include_owned_accounts=true); omitted otherwise.", "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" } ] }, "amount": { "description": "Signed amount in the currency's smallest precision units.", "example": "2375000000", "type": "string" }, "available_at": { "description": "ISO 8601 timestamp these funds became (or are scheduled to become) withdrawable: the posted time for already-settled funds, or 00:00:00 UTC on the scheduled release date for pending funds. Present only on inflows entering the balance (payments, top-ups, incoming transfers/affiliate); null on payouts, refunds, disputes and on-chain rows. The available_after/before filters window on its UTC settlement date.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Currency for this ledger activity.", "properties": { "code": { "description": "Currency code.", "example": "usd", "type": "string" }, "precision": { "description": "Precision factor for the currency, for example `100000000` for USD.", "example": "100000000", "type": "string" } }, "required": [ "code", "precision" ], "type": "object" }, "id": { "description": "Ledger activity ID.", "example": "line_3", "type": "string" }, "ledger_account_id": { "description": "The ledger account (a ldgr_ identifier) this row belongs to. Present only when the response aggregates owned accounts (include_owned_accounts=true); omitted otherwise. Pair it with `account` to scope drawers and dashboard links to the owning business.", "example": "ldgr_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "line_type": { "description": "The ledger line category this activity was posted under.", "enum": [ "ad_budget_release", "ad_campaign_budget", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "affiliate_fee", "airdrop", "airdrop_link_created", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payout", "balance_reservation", "balance_reservation_reversal", "bank_transfer", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_void", "card_spend_refund", "card_unload_deposit", "card_unload_transfer", "company_referral", "connected_account_negative_balance", "cross_border_percentage_fee", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold_adjustment", "dispute_representment_fee", "external_card_load_deposit", "fraud_prevention_fee", "fx_percentage_fee", "high_risk_merchant_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onchain_deposit", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "passthrough_gmv", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_referral", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_reversal", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payout_fee", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_earning", "promo_reversal", "referral_bonus", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "treasury_payin", "whop_processing_fee", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "example": "payment_gross", "type": "string" }, "object": { "enum": [ "ledger_activity" ], "example": "ledger_activity", "type": "string" }, "payment": { "description": "Payment related to this ledger activity. Included when rich resource hydration is enabled and the movement is tied to a payment.", "oneOf": [ { "properties": { "amount": { "description": "Total charged by the payment.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "card_brand": { "description": "Card brand, when the customer paid by card.", "type": [ "string", "null" ] }, "card_last4": { "description": "Last four digits of the card, when the customer paid by card.", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was created.", "format": "date-time", "type": "string" }, "id": { "description": "Payment ID, prefixed `pay_`.", "type": "string" }, "object": { "enum": [ "payment" ], "example": "payment", "type": "string" }, "payment_method_type": { "description": "How the customer paid, such as `card` or `paypal`.", "type": [ "string", "null" ] }, "payment_processor": { "description": "Processor that handled the payment, such as `stripe`.", "type": [ "string", "null" ] }, "plan": { "description": "Plan associated with the payment, when applicable.", "properties": { "id": { "description": "Plan ID, prefixed `plan_`.", "type": "string" }, "name": { "description": "Plan name.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "product": { "description": "Product associated with the payment, when applicable.", "properties": { "id": { "description": "Product ID, prefixed `prod_`.", "type": "string" }, "name": { "description": "Product name.", "type": "string" } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "user": { "description": "Customer associated with the payment. Email requires member:email:read.", "properties": { "email": { "description": "Customer email, or null without member:email:read.", "type": [ "string", "null" ] }, "id": { "description": "Customer ID, prefixed `user_`.", "type": "string" }, "name": { "description": "Customer display name.", "type": "string" } }, "required": [ "id", "name", "email" ], "type": [ "object", "null" ] } }, "required": [ "object", "id", "amount", "payment_method_type", "payment_processor", "card_brand", "card_last4", "user", "product", "plan", "created_at" ], "type": "object" }, { "type": "null" } ] }, "payment_id": { "description": "Payment ID for any payment-related activity, including refunds and disputes.", "type": [ "string", "null" ] }, "plan_id": { "description": "ID of the plan associated with the payment, when applicable.", "type": [ "string", "null" ] }, "plan_name": { "description": "Name of the plan associated with the payment, when applicable.", "type": [ "string", "null" ] }, "posted_at": { "description": "When the activity posted to the ledger.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "product_id": { "description": "ID of the product associated with the payment, when applicable.", "type": [ "string", "null" ] }, "product_name": { "description": "Name of the product associated with the payment, when applicable.", "type": [ "string", "null" ] }, "resource": { "description": "Resource associated with this ledger activity.", "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" }, { "properties": { "id": { "description": "Bounty ID.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "bounty" ], "example": "bounty", "type": "string" }, "status": { "description": "Bounty lifecycle status.", "example": "published", "type": "string" }, "title": { "description": "Bounty title.", "example": "Film a 60-second ceramic coating time-lapse", "type": "string" } }, "required": [ "object", "id", "title", "status" ], "type": "object" }, { "properties": { "id": { "description": "Ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "ledger_account" ], "example": "ledger_account", "type": "string" }, "owner": { "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "object", "id", "owner" ], "type": "object" }, { "properties": { "bank": { "properties": { "account_name": { "description": "Bank account holder name.", "example": "Shine Time Auto Detailing LLC", "type": [ "string", "null" ] }, "account_type": { "description": "Bank account type.", "example": "checking", "type": [ "string", "null" ] }, "bank_name": { "description": "Bank name.", "example": "Frost Bank", "type": [ "string", "null" ] }, "last4": { "description": "Last four digits of the bank account.", "example": "3311", "type": [ "string", "null" ] } }, "required": [ "bank_name", "account_name", "last4", "account_type" ], "type": [ "object", "null" ] }, "card": { "properties": { "brand": { "description": "Card brand.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Card expiration month.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Card expiration year.", "example": 2031, "type": [ "integer", "null" ] }, "last4": { "description": "Last four digits of the card.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "email_identifier": { "description": "Email identifier for email-based payment methods.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "gateway_type": { "description": "Payment gateway type.", "example": "plaid", "type": [ "string", "null" ] }, "id": { "description": "Payment method ID.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "payment_method" ], "example": "payment_method", "type": "string" }, "payment_method_type": { "description": "Payment method type.", "example": "us_bank_account", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payment_method_type", "gateway_type", "card", "bank", "email_identifier" ], "type": "object" }, { "properties": { "account_reference": { "description": "Masked account reference.", "example": "••••0472", "type": [ "string", "null" ] }, "destination_currency_code": { "description": "Destination currency code.", "example": "usd", "type": [ "string", "null" ] }, "id": { "description": "Payout method ID.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "Payout institution name.", "example": "Frost Bank", "type": [ "string", "null" ] }, "nickname": { "description": "Payout method nickname.", "example": "Ops checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "provider": { "description": "Payout provider.", "example": "masspay", "type": [ "string", "null" ] } }, "required": [ "object", "id", "nickname", "institution_name", "account_reference", "provider", "destination_currency_code" ], "type": "object" }, { "properties": { "authorized_at": { "description": "ISO 8601 timestamp the transaction was authorized.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "card_id": { "description": "Identifier of the card that the transaction was charged to.", "example": "icrd_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "cashback_usd": { "description": "Cashback earned on this transaction as a USD decimal string. Zero for declined or ineligible transactions; null when cashback has not been computed yet.", "example": "0.97", "type": [ "string", "null" ] }, "declined_reason": { "description": "Reason the transaction was declined (when status is declined).", "example": "Insufficient funds", "type": [ "string", "null" ] }, "id": { "description": "Card transaction ID.", "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "local_amount": { "description": "Amount the merchant charged in their local currency, as a decimal string. Pair with local_currency.", "example": "64.97", "type": [ "string", "null" ] }, "local_currency": { "description": "ISO 4217 currency code of the merchant-charged amount in local_amount.", "example": "usd", "type": [ "string", "null" ] }, "merchant_category": { "description": "Merchant category.", "example": "Car Care Supplies", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "Merchant icon URL.", "example": "https://icons.example.com/lone-star-detail-supply.png", "type": [ "string", "null" ] }, "merchant_name": { "description": "Merchant display name.", "example": "Lone Star Detail Supply", "type": [ "string", "null" ] }, "object": { "enum": [ "card_transaction" ], "example": "card_transaction", "type": "string" }, "posted_at": { "description": "ISO 8601 timestamp the transaction was settled by the card network.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "Current card transaction status.", "example": "completed", "type": [ "string", "null" ] }, "usd_amount": { "description": "The processor-settled USD amount as a decimal string. The ledger's USDT leg is posted 1:1 from this value.", "example": "64.97", "type": [ "string", "null" ] } }, "required": [ "object", "id", "card_id", "merchant_name", "merchant_icon_url", "merchant_category", "status", "usd_amount", "local_amount", "local_currency", "cashback_usd", "authorized_at", "posted_at", "declined_reason" ], "type": "object" }, { "type": "null" } ] }, "source": { "additionalProperties": true, "description": "Source of this ledger activity.", "properties": { "amount_float": { "description": "Payout amount as a decimal number in the destination currency (payout sources only; requires payout:withdrawal:read).", "example": 1500.0, "type": [ "number", "null" ] }, "card_brand": { "description": "Card brand used by the payment source.", "type": [ "string", "null" ] }, "chain": { "description": "Chain the deposit landed on, for example plasma (onchain_transaction sources only).", "example": "plasma", "type": [ "string", "null" ] }, "claim_url": { "description": "Public claim URL for the airdrop link (airdrop_link sources only).", "example": "https://whop.com/claim", "type": [ "string", "null" ] }, "created_at": { "description": "Payout creation time as an ISO 8601 timestamp (payout sources only; requires payout:withdrawal:read).", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated arrival as an ISO 8601 timestamp (payout sources only; requires payout:withdrawal:read).", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "from_amount": { "description": "Amount converted out of from_currency as a decimal string (swap sources only).", "example": "502.51", "type": [ "string", "null" ] }, "from_currency": { "description": "Lowercase currency code converted from (swap sources only).", "example": "usdt", "type": [ "string", "null" ] }, "id": { "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "object": { "example": "airdrop_link", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout (payout sources only; requires payout:withdrawal:read).", "example": "MassPay", "type": [ "string", "null" ] }, "payment_amount": { "description": "Total charged by the payment source.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "payment_method_type": { "description": "Payment method used by the payment source.", "type": [ "string", "null" ] }, "payment_processor": { "description": "Processor used by the payment source.", "type": [ "string", "null" ] }, "payout_destination": { "description": "Payout destination display info (payout sources only).", "properties": { "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-activity-icon", "type": [ "string", "null" ] }, "payer_name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "payout_token_nickname": { "description": "Saved payout destination nickname (payout sources only).", "example": "Ops checking", "type": [ "string", "null" ] }, "reason": { "description": "Why the activity happened. On transfer sources this is the transfer reason, for example pool_top_up or bounty_return. On payout sources it explains why the payout was canceled, denied, or failed (requires payout:withdrawal:read); null while the payout is progressing normally.", "example": "bounty_payout", "type": [ "string", "null" ] }, "risk_review_hold": { "description": "Whether this payout is currently held for manual risk review (payout sources only; requires payout:withdrawal:read).", "example": false, "type": [ "boolean", "null" ] }, "sender_address": { "description": "Sender wallet address or onramp provider identifier (onchain_transaction sources only).", "example": "0x8a4de51b9c37f2e6a0d1b8c94e5f7a2d3c6b0e19", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle status. On payout sources this is the payout status (requires payout:withdrawal:read); on airdrop_link sources it is the claim-link status (ungated); on payment and top-up sources it is the friendly payment status such as succeeded/pending/failed (ungated).", "example": "fully_claimed", "type": [ "string", "null" ] }, "to_amount": { "description": "Amount received in to_currency as a decimal string (swap sources only).", "example": "500.0", "type": [ "string", "null" ] }, "to_currency": { "description": "Lowercase currency code converted to (swap sources only).", "example": "usd", "type": [ "string", "null" ] }, "tx_hash": { "description": "On-chain transaction hash (onchain_transaction and swap sources only).", "example": "0x5d84a1c7e2f9b036d48c5a7e1b9f2d6c3a8e0b4f7c1d9e5a2b6f8c0d3e7a1b52", "type": [ "string", "null" ] } }, "required": [ "object", "id" ], "type": [ "object", "null" ] }, "user_email": { "description": "Email of the customer associated with the payment. Requires member:email:read.", "type": [ "string", "null" ] }, "user_id": { "description": "ID of the customer associated with the payment.", "type": [ "string", "null" ] }, "user_name": { "description": "Display name of the customer associated with the payment.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "line_type", "amount", "currency", "posted_at", "available_at", "resource", "source" ], "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" }, "LocationTargetingOption": { "properties": { "code": { "description": "The standardized code the ad-group `regions` field takes: an ISO 3166-1 code for countries (`US`) or an ISO 3166-2 code for states and provinces (`US-CA`, `CA-ON`). Null for a location that has no standard code, such as a city or a metro area — target those by `key` in the `regions` cities list instead.", "example": "US", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 code of the country the location sits in.", "example": "US", "type": [ "string", "null" ] }, "country_name": { "description": "Name of the country the location sits in.", "example": "United States", "type": [ "string", "null" ] }, "key": { "description": "The ad platform's key for the location in its location taxonomy. Use it as the `key` of a `regions` city or zip entry.", "example": "US", "type": "string" }, "location_type": { "description": "Granularity of the location. Which of these an ad platform reports depends on how finely it divides its location taxonomy.", "enum": [ "country", "region", "city", "zip", "neighborhood", "subcity", "medium_geo_area", "district", "dma" ], "example": "country", "type": "string" }, "name": { "description": "Display name, such as `California`.", "example": "United States", "type": "string" }, "region": { "description": "Name of the state or province a city sits in. Null for everything but cities.", "example": "Texas", "type": [ "string", "null" ] }, "type": { "description": "Always `locations`. The option goes in the ad-group `regions` field.", "enum": [ "locations" ], "example": "locations", "type": "string" } }, "required": [ "type", "location_type", "key", "name", "code", "country_code", "country_name", "region" ], "title": "Location", "type": "object" }, "MarketplaceStatuses": { "description": "The available marketplace statuses to choose from.", "enum": [ "not_available", "pending_review", "live_marketplace" ], "type": "string" }, "MediaAsset": { "properties": { "amount_charged": { "description": "USD amount charged to the account's balance for this generation. `null` if the generation wasn't billed.", "example": 2.5, "type": [ "number", "null" ] }, "completed_at": { "description": "ISO 8601 timestamp when the asset reached a terminal state. `null` while `processing`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "ISO 8601 timestamp when the generation was requested.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency of `amount_charged`. Always `usd`.", "example": "usd", "type": "string" }, "error_message": { "description": "Why generation failed. `null` unless status is `failed`.", "example": "The generation provider rejected the prompt. The charge was refunded.", "type": [ "string", "null" ] }, "file": { "description": "The produced file, usable anywhere attachments are accepted. `null` until the asset is `ready`.", "oneOf": [ { "$ref": "#/components/schemas/MediaAssetFile" }, { "type": "null" } ] }, "generation": { "$ref": "#/components/schemas/MediaAssetGeneration", "description": "The inputs the asset was generated from." }, "id": { "description": "Media asset ID, prefixed `media_`.", "example": "media_xxxxxxxxxxxxxx", "type": "string" }, "media_type": { "description": "The kind of media this asset holds.", "enum": [ "video", "image" ], "example": "video", "type": "string" }, "source": { "description": "How the asset was created. Always `generated`.", "enum": [ "generated" ], "example": "generated", "type": "string" }, "status": { "description": "Lifecycle state: `processing` while generation runs, `ready` when the file is available, `failed` when generation failed and the charge was refunded.", "enum": [ "processing", "ready", "failed" ], "example": "ready", "type": "string" } }, "required": [ "id", "media_type", "source", "status", "amount_charged", "currency", "error_message", "created_at", "completed_at", "generation", "file" ], "type": "object" }, "MediaAssetFile": { "properties": { "id": { "description": "File ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "CDN URL for downloading the file.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "url" ], "type": "object" }, "MediaAssetGeneration": { "properties": { "duration_seconds": { "description": "Requested video length in seconds. `null` for images.", "example": 5, "type": [ "number", "null" ] }, "prompt": { "description": "What the asset was generated from.", "example": "A 9:16 product showcase of a cordless power scrubber", "type": "string" }, "reference_media": { "items": { "description": "Reference image file IDs (`file_` prefixed) supplied at generation time.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "resolution": { "description": "Requested video resolution. `null` for images. `1080p` is not supported by Seedance 2.0 Fast or Mini; `4k` is only supported by Seedance 2.0.", "enum": [ "480p", "720p", "1080p", "4k", null ], "example": "1080p", "type": [ "string", "null" ] } }, "required": [ "prompt", "reference_media", "duration_seconds", "resolution" ], "type": "object" }, "Member": { "properties": { "access_level": { "description": "What the member can reach on the account: `customer` for paying members, `admin` for team members, `no_access` once every grant has lapsed.", "enum": [ "no_access", "admin", "customer" ], "example": "customer", "type": "string" }, "account_id": { "description": "The account this member belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the member record was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Member ID, prefixed `mber_`.", "example": "mber_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "When the member first joined the account, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "last_accessed_at": { "description": "When the member last opened the account's content, as an ISO 8601 timestamp. `null` if they never have.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "phone_number": { "description": "The member's phone number, or `null`. Their account number when they have shared one with this seller; otherwise the most recent number collected (or verified) at checkout.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "`joined` while the member is part of the account, `left` after they leave.", "enum": [ "joined", "left" ], "example": "joined", "type": "string" }, "user": { "description": "The user behind this member. `null` when the buyer is another business rather than a person.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] } }, "required": [ "id", "account_id", "access_level", "status", "phone_number", "joined_at", "last_accessed_at", "created_at", "user" ], "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 member's content access level. `admin` means their team role grants administrative content access, `customer` means they hold a valid product membership, and `no_access` means they cannot access company content." }, "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": { "properties": { "account": { "$ref": "#/components/schemas/StorefrontAccount", "description": "The account (seller) this membership belongs to." }, "cancel_at_period_end": { "description": "Whether the membership is set to cancel when the current billing period ends. Only meaningful for recurring plans.", "example": false, "type": "boolean" }, "created_at": { "description": "When the membership was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "current_period_end": { "description": "When the current billing period renews, or when a non-renewing membership expires, as an ISO 8601 timestamp. `null` for one-time purchases with no expiration.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Membership ID, prefixed `mem_`.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "license_key": { "description": "The software license key for this membership. Only present when the product includes a software licensing experience.", "example": "WHOP-XXXX-XXXX-XXXX", "type": [ "string", "null" ] }, "member": { "description": "The caller's member row on the account. Present only when the membership belongs to the caller; `null` on seller-side reads.", "oneOf": [ { "$ref": "#/components/schemas/MembershipMember" }, { "type": "null" } ] }, "metadata": { "description": "Custom key-value pairs stored on the membership, commonly used for software licensing.", "example": {}, "type": "object" }, "phone_number": { "description": "The buyer's phone number recorded for this membership, or `null`. The number collected (or verified) at checkout when the seller's phone collection is on; falls back to the buyer's account number when they have shared one with this seller.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "plan_id": { "description": "The plan the buyer purchased, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "product_id": { "description": "The product this membership grants access to, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Billing state of the membership. `active`/`trialing` memberships grant access; `past_due` is the grace period after a failed payment; `completed` one-time purchases keep access; `canceled`/`expired` do not.", "enum": [ "trialing", "active", "past_due", "completed", "canceled", "expired", "unresolved" ], "example": "active", "type": "string" }, "user_id": { "description": "The buyer, prefixed `user_`. `null` when the buyer is another business or the membership is unclaimed.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "status", "user_id", "product_id", "plan_id", "license_key", "phone_number", "cancel_at_period_end", "current_period_end", "metadata", "created_at", "member", "account" ], "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" } ] }, "cancelation_status": { "description": "Whether the customer is canceling, left, or was won back. Null if the membership has no cancellation reason or its cancellation state is indeterminate.", "oneOf": [ { "$ref": "#/components/schemas/CancelationStatus" }, { "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.", "example": "ch_xxxxxxxxxxxxxxx", "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" } ] }, "formatted_renewal_price": { "description": "The recurring renewal price for this membership, formatted with currency symbol and billing interval. Null if the membership is not recurring.", "example": "$25.00 / month", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "initial_price_paid": { "description": "The amount the customer paid when first purchasing this membership, formatted with currency symbol.", "example": "$25.00", "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, 100 chars per key, 500 chars per string 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. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "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 and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "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" ] }, "profile_pic": { "description": "The URL of the user's profile picture. Use profilePicture for the full attachment object.", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name", "email", "profile_pic" ], "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", "cancelation_status", "cancellation_reason", "canceled_at", "currency", "formatted_renewal_price", "initial_price_paid", "company", "plan", "promo_code", "product", "license_key", "metadata", "payment_collection_paused", "checkout_configuration_id" ], "type": "object" }, "MembershipMember": { "properties": { "access_level": { "description": "What the member can reach on the account: `customer` for paying members, `admin` for team members, `no_access` once every grant has lapsed.", "enum": [ "no_access", "admin", "customer" ], "example": "customer", "type": "string" }, "last_accessed_at": { "description": "When the member last opened the account's content, as an ISO 8601 timestamp. `null` if they never have.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "position": { "description": "The member's sort position in the buyer's own account list. `null` until they arrange it.", "example": 1767268800000.0, "type": [ "number", "null" ] } }, "required": [ "access_level", "last_accessed_at", "position" ], "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" }, "Money": { "properties": { "amount": { "description": "The amount in major units, as an exact decimal string — `\"10.00\"` is ten dollars. A string so no float rounds it in transit.", "example": "-2.50", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 currency code, lowercase.", "example": "usd", "type": "string" }, "decimals": { "description": "How many decimal places the amount CARRIES — the precision the charge itself runs at.", "example": 2, "type": "integer" }, "display_decimals": { "description": "How many decimal places to SHOW. Usually equal to `decimals`, and deliberately not always: COP is charged in centavos but written in whole pesos, so it is `2` and `0`. Format the number in your own locale using this.", "example": 2, "type": "integer" } }, "required": [ "currency", "amount", "decimals", "display_decimals" ], "type": "object" }, "MuxAssetStatuses": { "description": "Mux asset statuses", "enum": [ "uploading", "created", "ready" ], "type": "string" }, "Notification": { "properties": { "account": { "description": "Account the notification belongs to. `null` when the notification is not associated with an account.", "oneOf": [ { "$ref": "#/components/schemas/NotificationAccount" }, { "type": "null" } ] }, "attachment_url": { "description": "Image displayed alongside the notification — the sender's avatar, or the default notification image.", "example": "https://ui-avatars.com/api/", "type": "string" }, "content": { "description": "The body text of the notification displayed to the user.", "example": "Tuesday 9:00 AM, Bay 2", "type": "string" }, "created_at": { "description": "When the notification was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "experience": { "description": "Experience the notification is related to. `null` when not tied to a specific experience.", "oneOf": [ { "$ref": "#/components/schemas/NotificationExperience" }, { "type": "null" } ] }, "id": { "description": "Notification ID. Feed rows carry a composite id that doubles as the list cursor.", "example": "ntfr_xxxxxxxxxxxxxx:xxxxxxxxxxxxx", "type": "string" }, "iframe_link": { "description": "The same destination on the app's own domain, which the Whop web and mobile clients embed instead of navigating to it. Only relevant if you render Whop apps yourself. `null` when the notification carries its own `link`.", "example": "https://whopappdomain0000001.apps.whop.com/experiences/exp_xxxxxxxxxxxxxx/bookings/upcoming", "type": [ "string", "null" ] }, "link": { "description": "The whop.com page the notification opens, as a normal top-level navigation. This is the link to use unless you host Whop apps yourself. `null` when the notification has no click-through destination.", "example": "https://whop.com/joined/shine-time-auto-detailing/bookings-xxxxxxxxxxxxxx/app/bookings/upcoming/", "type": [ "string", "null" ] }, "mentions_me": { "description": "Whether the authenticated user was directly mentioned in this notification.", "example": false, "type": "boolean" }, "rest_path": { "description": "Additional path information appended to the notification's deep link, if any.", "example": "/bookings/upcoming", "type": [ "string", "null" ] }, "sender": { "description": "User who triggered the notification. `null` when it was system-generated.", "oneOf": [ { "$ref": "#/components/schemas/NotificationSender" }, { "type": "null" } ] }, "subject": { "description": "The title line of the notification displayed to the user.", "example": "Your ceramic coating is booked", "type": "string" }, "topic": { "description": "Topic category the notification belongs to, used for grouping and preference management. `null` when uncategorized.", "oneOf": [ { "$ref": "#/components/schemas/NotificationTopicSummary" }, { "type": "null" } ] } }, "required": [ "id", "subject", "content", "link", "iframe_link", "rest_path", "created_at", "attachment_url", "account", "experience", "topic", "sender", "mentions_me" ], "type": "object" }, "NotificationAccount": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL. `null` when the account has not uploaded one.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "URL slug of the account's store page on whop.com.", "example": "shine-time-auto-detailing", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "NotificationBadge": { "properties": { "account_id": { "description": "Account the experience belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the badge counts, prefixed `exp_`.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "has_unread": { "description": "Whether the caller has unread notifications in this experience.", "example": false, "type": "boolean" }, "important_count": { "description": "Number of unread important (mention) notifications in this experience.", "example": 0, "type": "integer" }, "last_viewed_at": { "description": "When the caller last viewed the experience, as an ISO 8601 timestamp. `null` when never viewed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "account_id", "experience_id", "has_unread", "important_count", "last_viewed_at" ], "type": "object" }, "NotificationExperience": { "properties": { "app": { "description": "App the experience belongs to.", "oneOf": [ { "$ref": "#/components/schemas/NotificationExperienceApp" }, { "type": "null" } ] }, "id": { "description": "Experience ID, prefixed `exp_`.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name of the experience.", "example": "Bookings", "type": [ "string", "null" ] } }, "required": [ "id", "name", "app" ], "type": "object" }, "NotificationExperienceApp": { "properties": { "icon_url": { "description": "Icon image URL. Always present — the default app icon when none is uploaded.", "example": "https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev/custom-perk-icon.svg", "type": "string" }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "icon_url" ], "type": "object" }, "NotificationPreferenceScope": { "properties": { "account_id": { "description": "Account the preference is scoped to (member notifications), prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "channel": { "description": "Delivery channel the preference applies to. `null` applies to every channel.", "enum": [ "in_app", "mobile", null ], "example": "in_app", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the preference is scoped to, prefixed `exp_`.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "team_account_id": { "description": "Account whose team notifications the preference is scoped to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "topic_id": { "description": "Notification topic the preference is scoped to, prefixed `topic_`.", "example": "topic_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "account_id", "team_account_id", "experience_id", "topic_id", "channel" ], "type": "object" }, "NotificationPreferenceState": { "properties": { "level": { "description": "What the user is now notified about in this scope, or `null` if the preference was cleared and the scope inherits its default again.", "enum": [ "all", "mentions", "nothing", null ], "example": "nothing", "type": [ "string", "null" ] }, "object": { "description": "Which kind of preference was written: `experience_notification_preference` for an experience level, `notification_preference` for a topic override.", "enum": [ "notification_preference", "experience_notification_preference" ], "example": "notification_preference", "type": "string" }, "scope": { "$ref": "#/components/schemas/NotificationPreferenceScope", "description": "The scope that was written, resolved. `null` on a dimension means the preference is not narrowed there." } }, "required": [ "object", "scope", "level" ], "type": "object" }, "NotificationSender": { "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "username": { "description": "Public username.", "example": "tanyacole", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "NotificationTopic": { "properties": { "default_preference_value": { "description": "Whether notifications for this topic are enabled by default when the user has not set a preference.", "example": false, "type": "boolean" }, "description": { "description": "Human-readable explanation of what notifications in this topic are about. `null` when no description has been set.", "example": "A customer books and pays for a detail", "type": [ "string", "null" ] }, "id": { "description": "Notification topic ID, prefixed `topic_`. This is the value the notification preference endpoints take as `topic_id`.", "example": "topic_xxxxxxxxxxxxxx", "type": "string" }, "identifier": { "description": "Stable, human-readable name for the category, such as `new-follower`. Unlike `id`, it is the same in every environment, which makes it the value to match on in code and to read in logs. Treat it as an opaque string: the set is open and the casing is historical rather than normalized.", "example": "notification_topic1_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "is_mention": { "description": "Whether this topic exclusively handles mention-based notifications.", "example": true, "type": "boolean" }, "name": { "description": "Display name shown in notification preference settings.", "example": "New sales", "type": "string" }, "topic_type": { "description": "Scope of the topic: whether it applies to an account, a user, or an account's team.", "enum": [ "account", "user", "account_team" ], "example": "account_team", "type": "string" } }, "required": [ "id", "identifier", "name", "description", "topic_type", "is_mention", "default_preference_value" ], "type": "object" }, "NotificationTopicSummary": { "properties": { "default_preference_value": { "description": "Whether notifications for this topic are enabled by default when the user has not set a preference.", "example": true, "type": "boolean" }, "id": { "description": "Notification topic ID, prefixed `topic_`.", "example": "topic_xxxxxxxxxxxxxx", "type": "string" }, "is_mention": { "description": "Whether this topic exclusively handles mention-based notifications.", "example": false, "type": "boolean" }, "topic_type": { "description": "Scope of the topic: whether it applies to an account, a user, or an account's team.", "enum": [ "account", "user", "account_team" ], "example": "user", "type": "string" } }, "required": [ "id", "topic_type", "is_mention", "default_preference_value" ], "type": "object" }, "OauthGrant": { "properties": { "account_id": { "description": "The account the grant is scoped to, prefixed `biz_`. `null` when the user authorized the app for themselves rather than for one of their accounts.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "app_id": { "description": "The app this grant authorizes, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "authorized_at": { "description": "When the user last authorized the app, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "When the user first authorized the app, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Grant ID, prefixed `oag_`.", "example": "oag_xxxxxxxxxxxxxx", "type": "string" }, "redirect_url": { "description": "Where to send the user to finish the flow: the `redirect_uri` you supplied with the authorization `code` appended, and `state` when you supplied one. Its scheme, host, port, and path come back exactly as sent — never re-cased or re-encoded — because the client matches them against its registered URI. Returned only once, on create: the code is single-use and expires 10 minutes after it is issued, so redirect immediately.", "example": "https://Booking.Shinetime.example:8443/oauth/Callback/", "type": "string" }, "revoked_at": { "description": "When the grant was revoked, as an ISO 8601 timestamp, or `null` while it is still in force. A revoked grant authorizes nothing — treat its `scopes` as no longer granted.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "scopes": { "items": { "description": "Every permission the user has granted this app, accumulated across authorizations, for example `member:basic:read`. `GET /api_keys/permissions` names and describes each one.", "example": "email", "type": "string" }, "type": "array" } }, "required": [ "id", "app_id", "account_id", "scopes", "authorized_at", "revoked_at", "created_at" ], "type": "object" }, "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", "type": [ "number", "null" ] }, "prev_page": { "description": "Previous page number", "type": [ "number", "null" ] }, "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" }, "Passkey": { "properties": { "created_at": { "description": "When the user registered this passkey, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "credential_id": { "description": "The WebAuthn credential ID as a base64url string. Pass it in `allowCredentials` when you run a ceremony against this specific passkey.", "example": "bGFwdG9wLWNyZWRlbnRpYWw", "type": "string" }, "id": { "description": "Passkey ID, prefixed `wcred_`. Use it to delete the passkey.", "example": "wcred_xxxxxxxxxxxxxx", "type": "string" }, "last_used_at": { "description": "When this passkey last completed a WebAuthn ceremony, as an ISO 8601 timestamp, or `null` if it never has.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "nickname": { "description": "The name the user gave this passkey, usually the device it lives on.", "example": "MacBook Pro", "type": "string" } }, "required": [ "id", "credential_id", "nickname", "last_used_at", "created_at" ], "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_exp_month": { "description": "The expiration month (1-12) of the card used for this payment. Falls back to the declined card on failed payments with no saved card. Null when the payment was not made with a card or the expiry is unavailable.", "example": 6, "type": [ "integer", "null" ] }, "card_exp_year": { "description": "The four-digit expiration year of the card used for this payment. Falls back to the declined card on failed payments with no saved card. Null when the payment was not made with a card or the expiry is unavailable.", "example": 2027, "type": [ "integer", "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.", "example": "ch_xxxxxxxxxxxxxxx", "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')." }, "customer_phone": { "description": "Phone number the customer provided at checkout, or their verified phone number when your checkout requires phone verification. `null` when no phone number was collected.", "type": [ "string", "null" ] }, "decline_code": { "description": "The reason the payment was declined. Null if the payment did not fail.", "oneOf": [ { "$ref": "#/components/schemas/PaymentDeclineCodes" }, { "type": "null" } ] }, "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" ] }, "fees": { "description": "The fees associated with this specific payment.", "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.", "example": "payment_processing_percentage_fee" } }, "required": [ "name", "amount", "currency", "type" ], "type": "object" }, "type": "array" }, "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" ] }, "needs_tracking": { "description": "Whether this payment is holding funds until the order ships and has no tracking number yet.", "type": [ "boolean", "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_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "card": { "description": "Card payments only: the card's network and last four.", "properties": { "brand": { "description": "The network identifier (`visa`, `amex`, …), matching `card.networks` entries and saved card payment methods.", "type": "string" }, "last4": { "description": "The card's last four digits, when captured.", "type": [ "string", "null" ] } }, "required": [ "brand", "last4" ], "type": [ "object", "null" ] }, "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "card", "icons" ], "type": [ "object", "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" ] }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "fingerprint", "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. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "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 and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "route": { "description": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "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" ] }, "refunds": { "description": "The refunds issued against this payment, newest first, including failed and canceled refund attempts. Limited to the 100 most recent.", "items": { "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" }, "status": { "$ref": "#/components/schemas/RefundStatuses", "description": "The current processing status of the refund, such as pending, succeeded, or failed." } }, "required": [ "id", "status", "amount", "currency", "created_at" ], "type": "object" }, "type": "array" }, "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`), or when it is a failed initial billing-engine payment on a `drafted` membership with an unlimited-stock plan; otherwise false. Used to decide if Whop can attempt the charge again.", "type": "boolean" }, "risk_score": { "description": "Whop's in-house fraud risk score for this payment, from 0 (lowest risk) to 100 (highest risk). Null when the payment has not been scored or scoring has not yet completed.", "example": 42, "type": [ "integer", "null" ] }, "risk_signals": { "additionalProperties": true, "description": "A curated set of factors behind the risk score, grouped by category (business transaction history, buyer, device). Each entry has a key, human-readable label, category, and value. Null when there is no risk assessment for this payment.", "type": [ "object", "null" ] }, "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" ] }, "settlement_time_at": { "description": "When this payment's funds post to the company's available balance, at midnight UTC. Known at payment time and never changes. The `ledger_account.funds_available` webhook carries the same `settlement_time_at` when that batch posts — match them to know these funds are now withdrawable.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "shipment": { "description": "The shipment attached to this payment.", "properties": { "carrier": { "description": "The shipping carrier detected for this shipment. Null until a tracking update identifies it.", "example": "usps", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "tracking_number": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "tracking_url": { "description": "A customer-facing URL to track this shipment's progress.", "example": "https://track.aftership.com/9400111899223456789012", "type": "string" } }, "required": [ "id", "status", "tracking_number", "carrier", "tracking_url" ], "type": [ "object", "null" ] }, "shipping_address": { "description": "The shipping address provided by the customer for physical goods. Null if no shipping address was collected.", "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" ] }, "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" ] }, "three_ds_verified": { "description": "Whether 3D Secure authentication was completed for this payment.", "type": "boolean" }, "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" ] }, "verification_checks": { "description": "The issuer's address and card security code check results for this payment. Null when the processor returned none.", "properties": { "address_line1": { "description": "Whether the billing street address the customer entered matched the address the issuer has on file.", "type": [ "string", "null" ] }, "card_holder_name": { "description": "Whether the cardholder name the customer entered matched the name the issuer has on file.", "type": [ "string", "null" ] }, "card_security_code": { "description": "Whether the CVV / CVC the customer entered matched the card.", "type": [ "string", "null" ] }, "zip_code": { "description": "Whether the billing postal code the customer entered matched the postal code the issuer has on file.", "type": [ "string", "null" ] } }, "required": [ "address_line1", "zip_code", "card_holder_name", "card_security_code" ], "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", "customer_phone", "payment_instrument", "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", "shipping_address", "needs_tracking", "shipment", "payment_method_type", "billing_reason", "payments_failed", "tax_amount", "tax_behavior", "failure_message", "decline_code", "metadata", "checkout_configuration_id", "settlement_time_at", "settlement_amount", "settlement_exchange_rate", "tax_refunded_amount", "fees", "card_exp_month", "card_exp_year", "financing_installments_count", "financing_transactions", "refunds", "disputes", "resolutions", "risk_score", "risk_signals", "three_ds_verified", "verification_checks" ], "type": "object" }, "PaymentBankTransfer": { "properties": { "account_number": { "description": "The account to send to, in the local scheme's format — `account_number_label` says what to call it.", "example": "4411 0902 33", "type": "string" }, "account_number_label": { "description": "What to call `account_number` when showing it, in the local scheme's own terms — `CLABE` in Mexico, for example.", "example": "Account number", "type": "string" }, "amount": { "$ref": "#/components/schemas/Money", "description": "Exactly what the buyer must send, in the charged currency." }, "bank_account_type": { "description": "The kind of account receiving the transfer, such as a checking account, in the local system's own vocabulary.", "example": "checking", "type": "string" }, "bank_address": { "description": "The receiving bank's address.", "example": "401 Congress Avenue, Austin, TX 78701", "type": "string" }, "bank_branch": { "description": "The receiving branch, where the local system routes by branch.", "example": "Burnet Road, Austin", "type": "string" }, "bank_code": { "description": "The receiving bank's code in the local clearing system.", "example": "684", "type": "string" }, "bank_name": { "description": "The receiving bank's name.", "example": "Frost Bank", "type": "string" }, "beneficiary_document": { "description": "The account holder's tax or identity document number, where the local system needs it to send.", "example": "74-2210318", "type": "string" }, "beneficiary_document_type": { "description": "What kind of document `beneficiary_document` is, in the local system's own vocabulary.", "example": "EIN", "type": "string" }, "beneficiary_name": { "description": "Who the account belongs to — the name the buyer's bank may ask them to confirm.", "example": "Shine Time Auto Detailing LLC", "type": "string" }, "document_url": { "description": "A hosted page with the complete, printable instructions. If you would rather not render the details yourself, send the buyer here.", "example": "https://psp.example/instructions/bank-transfer/shine-8237", "type": "string" }, "expires_at": { "description": "When these details stop being payable, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "instructions": { "description": "The rail's own step-by-step payment text, when it supplies one.", "example": "Send the exact amount from your own bank account and include the reference SHINE-8237 so the transfer can be matched to your order.", "type": "string" }, "reference": { "description": "The reference the buyer must attach to the transfer so it can be matched to this payment.", "example": "SHINE-8237", "type": "string" }, "routing_number": { "description": "The receiving bank's routing number for US transfers.", "example": "111900659", "type": "string" }, "secondary_account_number": { "description": "A second account number, where the rail publishes the same destination in more than one format.", "example": "114-000-093", "type": "string" }, "secondary_account_number_label": { "description": "What to call `secondary_account_number` when showing it.", "example": "ACH routing number", "type": "string" } }, "required": [], "type": "object" }, "PaymentBankTransferInstructions": { "properties": { "bank_transfer": { "$ref": "#/components/schemas/PaymentBankTransfer", "description": "The account details to show." }, "kind": { "description": "Always `bank_transfer`: account details the buyer sends money to from their own bank.", "enum": [ "bank_transfer" ], "example": "bank_transfer", "type": "string" } }, "required": [ "kind", "bank_transfer" ], "title": "Bank transfer", "type": "object" }, "PaymentBillingDetailsPreview": { "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code.", "example": "AR", "type": [ "string", "null" ] }, "email": { "description": "Email supplied when the method was collected.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "name": { "description": "Name on the payment method.", "example": "Buyer Name", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "C1043", "type": [ "string", "null" ] } }, "required": [ "email", "name", "country", "postal_code" ], "type": "object" }, "PaymentDeclineCodes": { "description": "The reason a payment was declined.", "enum": [ "insufficient_funds", "lost_card", "stolen_card", "expired_card", "suspected_fraud", "invalid_card_number", "invalid_cvc", "invalid_cvc_or_expiration", "incorrect_pin", "authentication_required", "card_not_supported", "currency_not_supported", "duplicate_transaction", "generic_decline", "invalid_account", "invalid_amount", "processing_error", "restricted_card", "card_velocity_exceeded", "contact_issuer", "bank_declined", "regulatory_blocked", "transaction_not_permitted", "transaction_stopped", "card_type_not_supported", "issuer_not_found", "closed_account", "issuer_unavailable", "invalid_zip", "invalid_expiry_month", "invalid_expiry_year", "invalid_expiry", "invalid_transaction", "cannot_authorize", "pin_required", "pin_try_exceeded", "provider_declined", "high_risk", "test_mode_decline", "merchant_blacklist", "reenter_transaction", "invalid_pin", "pin_required_as", "withdrawal_count_limit_exceeded", "invalid_country", "issuer_error", "invalid_card_holder_name", "no_accounts", "transaction_cancelled", "three_d_secure_success", "three_d_secure_canceled", "three_d_secure_invalid_card_number", "three_d_secure_generic_error", "three_d_secure_timeout", "three_d_secure_failed", "three_d_secure_card_not_enrolled", "three_d_secure_fraud", "three_d_secure_too_many_attempts", "three_d_secure_rejected_by_bank", "three_d_secure_reported_lost_or_stolen", "blocked_by_cardholder", "test_mode_test_card", "try_again_later", "transaction_not_allowed", "bank_insufficient_funds", "bank_account_not_found", "bank_account_closed", "bank_account_frozen", "bank_invalid_routing_number", "bank_non_transaction_account", "bank_authorization_revoked", "bank_payment_stopped", "bank_not_authorized", "bank_account_holder_deceased", "bank_duplicate", "bank_amount_error", "bank_regulatory_blocked", "bank_details_invalid", "bank_processing_error", "bank_generic_decline", "sepa_invalid_iban", "sepa_no_mandate", "sepa_mandate_data_invalid", "sepa_disputed", "sepa_refused_by_customer", "sepa_generic_decline" ], "type": "string" }, "PaymentInstructions": { "description": "What to show the buyer so they can pay. `kind` picks the shape and the details sit under the key named for it, so switching on `kind` gives you exactly that kind's payload. Every detail field is optional — the rails behind these methods publish them unevenly — but a kind that arrives with `document_url` can always fall back to sending the buyer to that hosted copy of the instructions.", "discriminator": { "mapping": { "bank_transfer": "#/components/schemas/PaymentBankTransferInstructions", "qr": "#/components/schemas/PaymentQrInstructions", "voucher": "#/components/schemas/PaymentVoucherInstructions" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/PaymentVoucherInstructions" }, { "$ref": "#/components/schemas/PaymentQrInstructions" }, { "$ref": "#/components/schemas/PaymentBankTransferInstructions" } ] }, "PaymentInstrument": { "properties": { "card": { "description": "Card payments only: the card's network and last four.", "oneOf": [ { "$ref": "#/components/schemas/PaymentInstrumentCard" }, { "type": "null" } ] }, "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "example": "Visa •••• 4242", "type": "string" }, "icons": { "$ref": "#/components/schemas/PaymentMethodIcons", "description": "The standard icon set: square and card shapes, each in light and dark colorways." }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "type": [ "number", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "example": "card", "type": "string" } }, "required": [ "payment_method_type", "display_name", "icons", "card", "installment_count" ], "type": "object" }, "PaymentInstrumentCard": { "properties": { "brand": { "description": "The network identifier (`visa`, `amex`, …), matching `card.networks` entries and saved card payment methods.", "example": "visa", "type": "string" }, "last4": { "description": "The card's last four digits, when captured.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4" ], "type": "object" }, "PaymentLastPaymentError": { "properties": { "code": { "description": "A machine-readable classification of the failure.", "example": "processing_error", "type": [ "string", "null" ] }, "decline_code": { "description": "The reason the payment was declined.", "enum": [ "insufficient_funds", "lost_card", "stolen_card", "expired_card", "suspected_fraud", "invalid_card_number", "invalid_cvc", "invalid_cvc_or_expiration", "incorrect_pin", "authentication_required", "card_not_supported", "currency_not_supported", "duplicate_transaction", "generic_decline", "invalid_account", "invalid_amount", "processing_error", "restricted_card", "card_velocity_exceeded", "contact_issuer", "bank_declined", "regulatory_blocked", "transaction_not_permitted", "transaction_stopped", "card_type_not_supported", "issuer_not_found", "closed_account", "issuer_unavailable", "invalid_zip", "invalid_expiry_month", "invalid_expiry_year", "invalid_expiry", "invalid_transaction", "cannot_authorize", "pin_required", "pin_try_exceeded", "provider_declined", "high_risk", "test_mode_decline", "merchant_blacklist", "reenter_transaction", "invalid_pin", "pin_required_as", "withdrawal_count_limit_exceeded", "invalid_country", "issuer_error", "invalid_card_holder_name", "no_accounts", "transaction_cancelled", "three_d_secure_success", "three_d_secure_canceled", "three_d_secure_invalid_card_number", "three_d_secure_generic_error", "three_d_secure_timeout", "three_d_secure_failed", "three_d_secure_card_not_enrolled", "three_d_secure_fraud", "three_d_secure_too_many_attempts", "three_d_secure_rejected_by_bank", "three_d_secure_reported_lost_or_stolen", "blocked_by_cardholder", "test_mode_test_card", "try_again_later", "transaction_not_allowed", "bank_insufficient_funds", "bank_account_not_found", "bank_account_closed", "bank_account_frozen", "bank_invalid_routing_number", "bank_non_transaction_account", "bank_authorization_revoked", "bank_payment_stopped", "bank_not_authorized", "bank_account_holder_deceased", "bank_duplicate", "bank_amount_error", "bank_regulatory_blocked", "bank_details_invalid", "bank_processing_error", "bank_generic_decline", "sepa_invalid_iban", "sepa_no_mandate", "sepa_mandate_data_invalid", "sepa_disputed", "sepa_refused_by_customer", "sepa_generic_decline", null ], "example": "insufficient_funds", "type": [ "string", "null" ] }, "message": { "description": "A human-readable explanation of the failure.", "example": "Your card was declined.", "type": [ "string", "null" ] } }, "required": [ "code", "decline_code", "message" ], "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.", "example": "ch_xxxxxxxxxxxxxxx", "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')." }, "customer_phone": { "description": "Phone number the customer provided at checkout, or their verified phone number when your checkout requires phone verification. `null` when no phone number was collected.", "type": [ "string", "null" ] }, "decline_code": { "description": "The reason the payment was declined. Null if the payment did not fail.", "oneOf": [ { "$ref": "#/components/schemas/PaymentDeclineCodes" }, { "type": "null" } ] }, "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" ] }, "needs_tracking": { "description": "Whether this payment is holding funds until the order ships and has no tracking number yet.", "type": [ "boolean", "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_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "card": { "description": "Card payments only: the card's network and last four.", "properties": { "brand": { "description": "The network identifier (`visa`, `amex`, …), matching `card.networks` entries and saved card payment methods.", "type": "string" }, "last4": { "description": "The card's last four digits, when captured.", "type": [ "string", "null" ] } }, "required": [ "brand", "last4" ], "type": [ "object", "null" ] }, "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "card", "icons" ], "type": [ "object", "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" ] }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "fingerprint", "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. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "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 and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "route": { "description": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "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`), or when it is a failed initial billing-engine payment on a `drafted` membership with an unlimited-stock plan; 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')." }, "shipment": { "description": "The shipment attached to this payment.", "properties": { "carrier": { "description": "The shipping carrier detected for this shipment. Null until a tracking update identifies it.", "example": "usps", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "tracking_number": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "tracking_url": { "description": "A customer-facing URL to track this shipment's progress.", "example": "https://track.aftership.com/9400111899223456789012", "type": "string" } }, "required": [ "id", "status", "tracking_number", "carrier", "tracking_url" ], "type": [ "object", "null" ] }, "shipping_address": { "description": "The shipping address provided by the customer for physical goods. Null if no shipping address was collected.", "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" ] }, "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", "customer_phone", "payment_instrument", "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", "shipping_address", "needs_tracking", "shipment", "payment_method_type", "billing_reason", "payments_failed", "tax_amount", "tax_behavior", "failure_message", "decline_code", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons" ], "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" ] }, "expired": { "description": "Whether the card is past its expiration month. An expired card cannot take a new charge.", "type": "boolean" }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "funding_type": { "description": "How the card is funded by the issuer. Null if the funding type could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardFundingTypes" }, { "type": "null" } ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] }, "three_ds_verified": { "description": "Whether this card was verified with 3D Secure, either when it was saved or on a payment that used it.", "type": "boolean" } }, "required": [ "brand", "fingerprint", "last4", "exp_month", "exp_year", "funding_type", "expired", "three_ds_verified" ], "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" }, "has_payer_document": { "description": "Whether this card has the payer identity document required by its payment provider.", "type": "boolean" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "has_payer_document", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "sepa_debit" ], "title": "SepaDebitPaymentMethod", "type": "object" } ], "type": "object" }, "PaymentMethodDisplay": { "properties": { "bank_debit": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `bank_debit`. Carries the account's last four when the linking provider surfaced it." }, "card": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `card`. What the collection surface displayed — the token has not been charged, so this is the buyer's claim, not the vault's record." }, "category": { "description": "The family the type belongs to.", "enum": [ "card", "wallet", "bank_debit", "bank_transfer", "voucher", "redirect", "crypto", "balance", "in_app_purchase", "saved" ], "example": "saved", "type": "string" }, "display_name": { "description": "Human-readable label for the method, e.g. `Visa •••• 4242`.", "example": "Visa •••• 4242", "type": "string" }, "id": { "description": "The saved payment method this preview came from, or `null` when the buyer supplied a new one.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "saved": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `saved` and the stored method is a card. Unlike the other previews this is the vault's own record, not a claim from the collection surface. Absent for a balance, which has no instrument." }, "type": { "description": "The payment method type, e.g. `card`, `apple_pay`, `klarna`.", "example": "card", "type": "string" }, "wallet": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `wallet`. Carries the backing card's brand and last four when the wallet surfaced them." } }, "required": [ "id", "type", "category", "display_name" ], "type": "object" }, "PaymentMethodDisplayPreview": { "properties": { "brand": { "description": "Lowercase card brand, e.g. `visa`. Absent when the method carries no brand.", "example": "visa", "type": "string" }, "last4": { "description": "Last four digits of the instrument. Absent when the method carries none.", "example": "4242", "type": "string" } }, "required": [], "type": "object" }, "PaymentMethodDomain": { "properties": { "account_id": { "description": "ID of the account the domain is registered for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "created_at": { "description": "When the domain was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "hostname": { "description": "Hostname the checkout is served from (e.g. `checkout.example.com`).", "example": "checkout.shinetime.example", "type": "string" }, "id": { "description": "Payment method domain ID, prefixed `pmd_`.", "example": "pmd_xxxxxxxxxxxxxx", "type": "string" }, "provider": { "description": "Wallet provider the domain is registered with.", "enum": [ "apple" ], "example": "apple", "type": "string" }, "status": { "description": "Verification status. `pending` means the provider could not fetch the domain-association file yet; only `verified` domains show wallet payment methods at checkout.", "enum": [ "pending", "verified" ], "example": "verified", "type": "string" }, "updated_at": { "description": "When the domain was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "hostname", "provider", "status", "created_at", "updated_at" ], "type": "object" }, "PaymentMethodIconFiles": { "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "PaymentMethodIconVariants": { "properties": { "dark": { "$ref": "#/components/schemas/PaymentMethodIconFiles", "description": "The colorway for dark surfaces." }, "light": { "$ref": "#/components/schemas/PaymentMethodIconFiles", "description": "The colorway for light surfaces." } }, "required": [ "light", "dark" ], "type": "object" }, "PaymentMethodIcons": { "properties": { "card": { "$ref": "#/components/schemas/PaymentMethodIconVariants", "description": "The credit-card-proportioned tile (48x30)." }, "square": { "$ref": "#/components/schemas/PaymentMethodIconVariants", "description": "The square tile (32x32)." } }, "required": [ "square", "card" ], "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons" ], "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" ] }, "expired": { "description": "Whether the card is past its expiration month. An expired card cannot take a new charge.", "type": "boolean" }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "funding_type": { "description": "How the card is funded by the issuer. Null if the funding type could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardFundingTypes" }, { "type": "null" } ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] }, "three_ds_verified": { "description": "Whether this card was verified with 3D Secure, either when it was saved or on a payment that used it.", "type": "boolean" } }, "required": [ "brand", "fingerprint", "last4", "exp_month", "exp_year", "funding_type", "expired", "three_ds_verified" ], "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" }, "has_payer_document": { "description": "Whether this card has the payer identity document required by its payment provider.", "type": "boolean" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "has_payer_document", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "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" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "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", "icons", "sepa_debit" ], "title": "SepaDebitPaymentMethod", "type": "object" } ], "type": "object" }, "PaymentMethodTypes": { "description": "The different types of payment methods that can be used.", "enum": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alma", "amazon_pay", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "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", "flex_pay", "gb_bank_transfer", "gcash", "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", "modo", "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", "rapipago", "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" }, "PaymentNextAction": { "description": "What the buyer must do to finish. `type` picks the shape and each type carries only its own `data`, so switching on `type` gives you exactly that step's payload.", "discriminator": { "mapping": { "await_confirmation": "#/components/schemas/PaymentNextActionAwaitConfirmation", "display_instructions": "#/components/schemas/PaymentNextActionDisplayInstructions", "redirect": "#/components/schemas/PaymentNextActionRedirect" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/PaymentNextActionRedirect" }, { "$ref": "#/components/schemas/PaymentNextActionDisplayInstructions" }, { "$ref": "#/components/schemas/PaymentNextActionAwaitConfirmation" } ] }, "PaymentNextActionAwaitConfirmation": { "properties": { "data": { "$ref": "#/components/schemas/PaymentNextActionAwaitConfirmationData", "description": "How long the wait can last." }, "render": { "items": { "description": "Where this step can be presented: `inline` inside your own page, `full_page` as a top-level navigation. Pick whichever listed mode suits your surface.", "enum": [ "inline", "full_page" ], "example": "inline", "type": "string" }, "type": "array" }, "type": { "description": "Always `await_confirmation`: nothing to show — the buyer has done their part and the rail settles out of band. Poll `status` until it moves.", "enum": [ "await_confirmation" ], "example": "await_confirmation", "type": "string" } }, "required": [ "type", "render", "data" ], "title": "Await confirmation", "type": "object" }, "PaymentNextActionAwaitConfirmationData": { "properties": { "expires_at": { "description": "When the confirmation window closes, as an ISO 8601 timestamp. A payment still unconfirmed by then will not succeed — watch `status` for the failed attempt.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "expires_at" ], "type": "object" }, "PaymentNextActionDisplayInstructions": { "properties": { "data": { "$ref": "#/components/schemas/PaymentInstructions", "description": "The instructions. `kind` picks the shape, and the details sit under the key named for it: `voucher`, `qr`, or `bank_transfer`." }, "render": { "items": { "description": "Where this step can be presented: `inline` inside your own page, `full_page` as a top-level navigation. Pick whichever listed mode suits your surface.", "enum": [ "inline", "full_page" ], "example": "inline", "type": "string" }, "type": "array" }, "type": { "description": "Always `display_instructions`: show the buyer `data` — what to pay, where, and by when. The payment completes once they pay and the rail confirms it, so keep polling `status`.", "enum": [ "display_instructions" ], "example": "display_instructions", "type": "string" } }, "required": [ "type", "render", "data" ], "title": "Display instructions", "type": "object" }, "PaymentNextActionRedirect": { "properties": { "data": { "$ref": "#/components/schemas/PaymentNextActionRedirectData", "description": "Where to send the buyer." }, "render": { "items": { "description": "Where this step can be presented: `inline` inside your own page, `full_page` as a top-level navigation. Pick whichever listed mode suits your surface.", "enum": [ "inline", "full_page" ], "example": "inline", "type": "string" }, "type": "array" }, "type": { "description": "Always `redirect`: send the buyer to `data.url`. The provider hands them back to `return_url` when they are done.", "enum": [ "redirect" ], "example": "redirect", "type": "string" } }, "required": [ "type", "render", "data" ], "title": "Redirect", "type": "object" }, "PaymentNextActionRedirectData": { "properties": { "frame_max_width": { "description": "The widest the provider's page lays out usefully, in CSS pixels — cap a frame or dialog presenting it at this width. `null` when the page fills whatever width it is given.", "example": 500, "type": [ "integer", "null" ] }, "url": { "description": "The provider's page for this payment, as an absolute URL — take the buyer there.", "example": "https://psp.example/3ds/challenge", "type": "string" } }, "required": [ "url", "frame_max_width" ], "type": "object" }, "PaymentProcessingDetails": { "properties": { "expected_by": { "description": "When the payment is expected to settle, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "expected_by" ], "type": "object" }, "PaymentProviders": { "description": "The different payment providers.", "enum": [ "stripe", "coinbase", "paypal", "apple", "sezzle", "splitit", "platform_balance", "multi_psp", "adyen", "claritypay", "flex_pay", "checkout_dot_com", "airwallex", "coinflow", "sequra", "dlocal", "masspay", "braintree" ], "type": "string" }, "PaymentQr": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Exactly what the buyer must pay, in the charged currency." }, "document_url": { "description": "A hosted page with the complete, printable instructions. If you would rather not render the details yourself, send the buyer here.", "example": "https://psp.example/qr/shine-4417", "type": "string" }, "expires_at": { "description": "When the code stops being payable, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "key": { "description": "An account key the buyer can pay to directly (Colombia's Bre-B llave), for apps that take a key instead of a scan.", "example": "marcus@shinetime.example", "type": "string" }, "qr_code": { "description": "The QR code's contents, ready to render as a scannable image — `qr_format` says how it is encoded.", "example": "pix.shinetime.example/qr/dana-4417", "type": "string" }, "qr_format": { "description": "How `qr_code` is encoded.", "example": "url", "type": "string" } }, "required": [], "type": "object" }, "PaymentQrInstructions": { "properties": { "kind": { "description": "Always `qr`: a code the buyer scans with their banking app.", "enum": [ "qr" ], "example": "qr", "type": "string" }, "qr": { "$ref": "#/components/schemas/PaymentQr", "description": "The code to show." } }, "required": [ "kind", "qr" ], "title": "QR", "type": "object" }, "PaymentStatus": { "properties": { "capture_expires_at": { "description": "When the card authorization must be captured, as an ISO 8601 timestamp. `null` when this payment was not authorized for later capture.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "The payment this status describes, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_error": { "description": "Details of the most recent failed attempt, or `null` when the payment has not failed.", "oneOf": [ { "$ref": "#/components/schemas/PaymentLastPaymentError" }, { "type": "null" } ] }, "next_action": { "description": "What the buyer must do next while `status` is `requires_action`, otherwise `null`. `type` picks the shape and each variant carries only its own `data`, so switching on `type` gives you exactly that step's payload.", "oneOf": [ { "$ref": "#/components/schemas/PaymentNextAction" }, { "type": "null" } ] }, "object": { "description": "Always `payment_status`.", "example": "payment_status", "type": "string" }, "processing_details": { "description": "Present while `status` is `processing` on a settlement rail, otherwise `null`.", "oneOf": [ { "$ref": "#/components/schemas/PaymentProcessingDetails" }, { "type": "null" } ] }, "return_url": { "description": "Where to send the buyer once the payment reaches a resting state, or `null` to leave them where they are. Editable until they return — see the return_url operation.", "example": "https://shinetime.example/checkout/done", "type": [ "string", "null" ] }, "status": { "description": "How far the payment has got. `requires_confirmation` — nothing attempted yet, or the last attempt failed and can be retried. `requires_action` — the buyer has a step outstanding; see `next_action`. `requires_capture` — the card authorization is holding funds and must be captured. `confirming` — the buyer has done their part and the processor is deciding. `processing` — the money is moving; see `processing_details`. `succeeded` — collected. `canceled` — voided or written off.", "enum": [ "requires_confirmation", "requires_action", "requires_capture", "confirming", "processing", "succeeded", "canceled" ], "example": "requires_action", "type": "string" } }, "required": [ "id", "object", "status", "next_action", "processing_details", "last_payment_error", "return_url", "capture_expires_at" ], "type": "object" }, "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" }, "PaymentVoucher": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Exactly what the buyer must pay, in the charged currency." }, "barcode": { "description": "The barcode's contents, when the voucher carries one — render it in the symbology named by `barcode_format`.", "example": "2379 1234 0560 0512 3401", "type": "string" }, "barcode_format": { "description": "The symbology `barcode` is encoded in, such as `CODE_128`.", "example": "CODE_128", "type": "string" }, "company_name": { "description": "Who the payment is made out to.", "example": "Shine Time Auto Detailing", "type": "string" }, "document_url": { "description": "A hosted page with the complete, printable instructions. If you would rather not render the details yourself, send the buyer here.", "example": "https://psp.example/vouchers/shine-0021-4479", "type": "string" }, "expires_at": { "description": "When the voucher stops being payable, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "provider_logo": { "description": "URL of that network's logo.", "example": "https://psp.example/logos/boleto.png", "type": "string" }, "provider_name": { "description": "The network the buyer pays at, such as OXXO.", "example": "Boleto Bancário", "type": "string" }, "reference": { "description": "The voucher's number — what the buyer reads out or types at the counter to pay.", "example": "0021-4479-8830-55", "type": "string" } }, "required": [], "type": "object" }, "PaymentVoucherInstructions": { "properties": { "kind": { "description": "Always `voucher`: a code the buyer pays in person, at a convenience store or bank counter.", "enum": [ "voucher" ], "example": "voucher", "type": "string" }, "voucher": { "$ref": "#/components/schemas/PaymentVoucher", "description": "The voucher to show." } }, "required": [ "kind", "voucher" ], "title": "Voucher", "type": "object" }, "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 payout 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 payout readiness.", "enum": [ "connected", "disabled", "action_required", "pending_verification", "verification_failed", "manual_review", "denied", "not_started", "blocked_by_parent" ], "type": "string" }, "PayoutDestinationCategory": { "description": "The category of a payout destination.", "enum": [ "crypto", "rtp", "next_day_bank", "bank_wire", "digital_wallet", "unknown" ], "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": "Frost 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": "Ops checking", "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": "Frost 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": "Ops checking", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "company", "nickname", "currency", "is_default", "account_reference", "institution_name", "destination" ], "type": "object" }, "Permission": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "access_pass:basic:export", "type": "string" }, "allowed_on_api_key": { "description": "Whether an API key can be granted the permission.", "example": true, "type": "boolean" }, "allowed_on_app": { "description": "Whether an app can request and be granted the permission.", "example": true, "type": "boolean" }, "allowed_on_user": { "description": "Whether the permission can be granted to user tokens.", "example": false, "type": "boolean" }, "category": { "description": "The category the action is grouped under, or `null` when uncategorized.", "example": "Products", "type": [ "string", "null" ] }, "description": { "description": "What granting the action allows.", "example": "Download the account's product list as a CSV.", "type": "string" }, "granted_to_system_roles": { "items": { "description": "System roles that include the permission.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser" ], "example": "owner", "type": "string" }, "type": "array" }, "name": { "description": "Human-readable name of the action.", "example": "Export products", "type": "string" } }, "required": [ "action", "name", "description", "category", "allowed_on_user", "allowed_on_app", "allowed_on_api_key", "granted_to_system_roles" ], "type": "object" }, "PermissionAction": { "description": "A permission action identifier, such as `company:basic:read`.", "enum": [ "ai_prompt:create", "access_pass:basic:export", "access_pass:basic:read", "access_pass:control_center", "access_pass:create", "access_pass:delete", "access_pass:stats:export", "access_pass:stats:read", "access_pass:update", "ad_campaign:basic:export", "ad_campaign:basic:read", "ad_campaign:conversion:create", "ad_campaign:create", "ad_campaign:credit:create", "ad_campaign:delete", "ad_campaign:read", "ad_campaign:stats:read", "ad_campaign:update", "audience:basic:read", "audience:update", "ad_publisher:read", "affiliate:basic:read", "affiliate:create", "affiliate:update", "authorized_user:create", "authorized_user:delete", "authorized_user:update", "authorized_role:create", "authorized_role:update", "authorized_role:delete", "authorized_role:attach", "authorized_role:detach", "app_authorization:create", "app_authorization:read", "app_authorization:update", "app_authorization:delete", "bounty:basic:read", "bounty:create", "bounty:capture_clip:create", "bounty:capture_clip:complete", "bounty:capture_clip:discard", "bounty:update", "bounty:submission:create", "bounty:submission:delete", "bounty:submission:vote", "chat:manage_webhook", "chat:moderate", "chat:message:create", "chat:read", "dms:read", "dms:message:manage", "dms:channel:manage", "forum:post:create", "forum:read", "forum:moderate", "company:authorized_user:read", "company:authorized_user:email:read", "company:balance:read", "company:balance:export", "company_token_transaction:read", "company_token_transaction:create", "company:log:read", "company:manage_checkout", "company:manage_legal", "company:basic:read", "company:update", "company:transfer_ownership", "company:create", "company:create_child", "company:suspend_child", "company:delete", "company:delete_child", "company:update_child_fees", "child_company:basic:export", "social_account:create", "social_account:delete", "social_account:read", "social_link:update", "custom_emoji:update", "content_rewards:basic:export", "content_rewards:basic:read", "content_rewards:create", "content_rewards:delete", "content_rewards:moderate_submission", "content_rewards:update", "developer:basic:read", "developer:create_app", "developer:manage_api_key", "developer:manage_oauth", "developer:manage_webhook", "developer:logs:read", "developer:manage_builds", "developer:update_app", "developer:update_app_authorization", "event:create", "experience:attach", "experience:create", "experience:delete", "experience:detach", "experience:hidden_experience:read", "experience:update", "iap:read", "identity:read", "identity:write", "incorporation:read", "incorporation:write", "livestream:create", "livestream:delete", "livestream:manage_recording", "livestream:chat:read", "livestream:chat:write", "livestream:moderate", "media:generate", "media:read", "member:basic:export", "member:basic:read", "member:email:read", "member:phone:read", "member:payment_methods:read", "member:payment_methods:use", "member:payment_methods:manage", "member:manage", "membership:cancel", "membership:resync_access", "membership:create", "membership:update", "membership:transfer", "member:moderate", "member:stats:export", "member:stats:read", "member:journey:read", "payment:basic:export", "payment:basic:read", "payment:charge", "payment:dispute", "payment:dispute:export", "payment:dispute:read", "payment:dispute_alert:read", "payment:setup_intent:read", "payment:setup_intent:manage", "payment:manage", "payment:resolution_center", "payment:resolution_center_case:export", "payment:resolution_center_case:read", "payment:resolution_center_case:manage", "payout:create_destination", "payout:delete_destination", "payout:destination:read", "payout:transfer_funds", "payout:transfer:read", "payout:transfer:export", "payout:update_destination", "payout:withdraw_funds", "payout:withdrawal:read", "payout:withdrawal:export", "payout:account:read", "payout:account:update", "plan:basic:export", "plan:basic:read", "plan:create", "plan:delete", "plan:stats:export", "plan:stats:read", "plan:update", "plan:waitlist:manage", "plan:waitlist:export", "plan:waitlist:read", "promo_code:basic:export", "promo_code:basic:read", "promo_code:create", "promo_code:delete", "promo_code:update", "referral:basic:read", "referral:partner:create", "partner:basic:read", "partner:email:read", "partner:invite:create", "partner:create", "stats:read", "support_chat:read", "support_chat:create", "support_chat:message:create", "tracking_link:basic:export", "tracking_link:basic:read", "tracking_link:create", "tracking_link:delete", "tracking_link:stats:export", "tracking_link:stats:read", "tracking_link:update", "courses:read", "courses:update", "course_lesson_interaction:read", "course_analytics:read", "lead:basic:read", "lead:basic:export", "invoice:create", "invoice:basic:read", "invoice:basic:export", "invoice:update", "webhook_receive:invoices", "webhook_receive:setup_intents", "webhook_receive:withdrawals", "webhook_receive:swaps", "webhook_receive:ledger_accounts", "webhook_receive:accounts", "webhook_receive:deposits", "webhook_receive:transfers", "webhook_receive:card_transactions", "webhook_receive:cards", "webhook_receive:card_applications", "webhook_receive:payout_methods", "webhook_receive:verifications", "webhook_receive:identity_profiles", "webhook_receive:payout_accounts", "webhook_receive:chat", "webhook_receive:entries", "webhook_receive:ad_campaigns", "webhook_receive:products", "webhook_receive:plans", "webhook_receive:shipments", "webhook_receive:members", "webhook_receive:exports", "webhook_receive:courses", "webhook_receive:memberships", "webhook_receive:payments", "webhook_receive:refunds", "webhook_receive:disputes", "webhook_receive:resolutions", "webhook_receive:app_payments", "webhook_receive:app_memberships", "shipment:create", "shipment:basic:read", "checkout_configuration:basic:read", "checkout_configuration:create", "checkout_configuration:delete", "checkout_request:create", "checkout_request:basic:read", "crypto_wallet:manage", "crypto_wallet:swap", "airdrop_link:basic:read", "airdrop_link:manage", "lead:manage", "notification:create", "user:balance:read", "user:email:read", "user:staff:read", "oauth:token_exchange", "openid", "profile", "email", "ai_chat:read", "ai_chat:create", "ai_chat:delete", "ai_chat:update", "user:notifications:read", "user:notifications:update", "user:profile:update" ], "example": "ai_prompt:create", "type": "string", "x-enumNames": [ "AiPromptCreate", "AccessPassBasicExport", "AccessPassBasicRead", "AccessPassControlCenter", "AccessPassCreate", "AccessPassDelete", "AccessPassStatsExport", "AccessPassStatsRead", "AccessPassUpdate", "AdCampaignBasicExport", "AdCampaignBasicRead", "AdCampaignConversionCreate", "AdCampaignCreate", "AdCampaignCreditCreate", "AdCampaignDelete", "AdCampaignRead", "AdCampaignStatsRead", "AdCampaignUpdate", "AudienceBasicRead", "AudienceUpdate", "AdPublisherRead", "AffiliateBasicRead", "AffiliateCreate", "AffiliateUpdate", "AuthorizedUserCreate", "AuthorizedUserDelete", "AuthorizedUserUpdate", "AuthorizedRoleCreate", "AuthorizedRoleUpdate", "AuthorizedRoleDelete", "AuthorizedRoleAttach", "AuthorizedRoleDetach", "AppAuthorizationCreate", "AppAuthorizationRead", "AppAuthorizationUpdate", "AppAuthorizationDelete", "BountyBasicRead", "BountyCreate", "BountyCaptureClipCreate", "BountyCaptureClipComplete", "BountyCaptureClipDiscard", "BountyUpdate", "BountySubmissionCreate", "BountySubmissionDelete", "BountySubmissionVote", "ChatManageWebhook", "ChatModerate", "ChatMessageCreate", "ChatRead", "DmsRead", "DmsMessageManage", "DmsChannelManage", "ForumPostCreate", "ForumRead", "ForumModerate", "CompanyAuthorizedUserRead", "CompanyAuthorizedUserEmailRead", "CompanyBalanceRead", "CompanyBalanceExport", "CompanyTokenTransactionRead", "CompanyTokenTransactionCreate", "CompanyLogRead", "CompanyManageCheckout", "CompanyManageLegal", "CompanyBasicRead", "CompanyUpdate", "CompanyTransferOwnership", "CompanyCreate", "CompanyCreateChild", "CompanySuspendChild", "CompanyDelete", "CompanyDeleteChild", "CompanyUpdateChildFees", "ChildCompanyBasicExport", "SocialAccountCreate", "SocialAccountDelete", "SocialAccountRead", "SocialLinkUpdate", "CustomEmojiUpdate", "ContentRewardsBasicExport", "ContentRewardsBasicRead", "ContentRewardsCreate", "ContentRewardsDelete", "ContentRewardsModerateSubmission", "ContentRewardsUpdate", "DeveloperBasicRead", "DeveloperCreateApp", "DeveloperManageApiKey", "DeveloperManageOauth", "DeveloperManageWebhook", "DeveloperLogsRead", "DeveloperManageBuilds", "DeveloperUpdateApp", "DeveloperUpdateAppAuthorization", "EventCreate", "ExperienceAttach", "ExperienceCreate", "ExperienceDelete", "ExperienceDetach", "ExperienceHiddenExperienceRead", "ExperienceUpdate", "IapRead", "IdentityRead", "IdentityWrite", "IncorporationRead", "IncorporationWrite", "LivestreamCreate", "LivestreamDelete", "LivestreamManageRecording", "LivestreamChatRead", "LivestreamChatWrite", "LivestreamModerate", "MediaGenerate", "MediaRead", "MemberBasicExport", "MemberBasicRead", "MemberEmailRead", "MemberPhoneRead", "MemberPaymentMethodsRead", "MemberPaymentMethodsUse", "MemberPaymentMethodsManage", "MemberManage", "MembershipCancel", "MembershipResyncAccess", "MembershipCreate", "MembershipUpdate", "MembershipTransfer", "MemberModerate", "MemberStatsExport", "MemberStatsRead", "MemberJourneyRead", "PaymentBasicExport", "PaymentBasicRead", "PaymentCharge", "PaymentDispute", "PaymentDisputeExport", "PaymentDisputeRead", "PaymentDisputeAlertRead", "PaymentSetupIntentRead", "PaymentSetupIntentManage", "PaymentManage", "PaymentResolutionCenter", "PaymentResolutionCenterCaseExport", "PaymentResolutionCenterCaseRead", "PaymentResolutionCenterCaseManage", "PayoutCreateDestination", "PayoutDeleteDestination", "PayoutDestinationRead", "PayoutTransferFunds", "PayoutTransferRead", "PayoutTransferExport", "PayoutUpdateDestination", "PayoutWithdrawFunds", "PayoutWithdrawalRead", "PayoutWithdrawalExport", "PayoutAccountRead", "PayoutAccountUpdate", "PlanBasicExport", "PlanBasicRead", "PlanCreate", "PlanDelete", "PlanStatsExport", "PlanStatsRead", "PlanUpdate", "PlanWaitlistManage", "PlanWaitlistExport", "PlanWaitlistRead", "PromoCodeBasicExport", "PromoCodeBasicRead", "PromoCodeCreate", "PromoCodeDelete", "PromoCodeUpdate", "ReferralBasicRead", "ReferralPartnerCreate", "PartnerBasicRead", "PartnerEmailRead", "PartnerInviteCreate", "PartnerCreate", "StatsRead", "SupportChatRead", "SupportChatCreate", "SupportChatMessageCreate", "TrackingLinkBasicExport", "TrackingLinkBasicRead", "TrackingLinkCreate", "TrackingLinkDelete", "TrackingLinkStatsExport", "TrackingLinkStatsRead", "TrackingLinkUpdate", "CoursesRead", "CoursesUpdate", "CourseLessonInteractionRead", "CourseAnalyticsRead", "LeadBasicRead", "LeadBasicExport", "InvoiceCreate", "InvoiceBasicRead", "InvoiceBasicExport", "InvoiceUpdate", "WebhookReceiveInvoices", "WebhookReceiveSetupIntents", "WebhookReceiveWithdrawals", "WebhookReceiveSwaps", "WebhookReceiveLedgerAccounts", "WebhookReceiveAccounts", "WebhookReceiveDeposits", "WebhookReceiveTransfers", "WebhookReceiveCardTransactions", "WebhookReceiveCards", "WebhookReceiveCardApplications", "WebhookReceivePayoutMethods", "WebhookReceiveVerifications", "WebhookReceiveIdentityProfiles", "WebhookReceivePayoutAccounts", "WebhookReceiveChat", "WebhookReceiveEntries", "WebhookReceiveAdCampaigns", "WebhookReceiveProducts", "WebhookReceivePlans", "WebhookReceiveShipments", "WebhookReceiveMembers", "WebhookReceiveExports", "WebhookReceiveCourses", "WebhookReceiveMemberships", "WebhookReceivePayments", "WebhookReceiveRefunds", "WebhookReceiveDisputes", "WebhookReceiveResolutions", "WebhookReceiveAppPayments", "WebhookReceiveAppMemberships", "ShipmentCreate", "ShipmentBasicRead", "CheckoutConfigurationBasicRead", "CheckoutConfigurationCreate", "CheckoutConfigurationDelete", "CheckoutRequestCreate", "CheckoutRequestBasicRead", "CryptoWalletManage", "CryptoWalletSwap", "AirdropLinkBasicRead", "AirdropLinkManage", "LeadManage", "NotificationCreate", "UserBalanceRead", "UserEmailRead", "UserStaffRead", "OauthTokenExchange", "Openid", "Profile", "Email", "AiChatRead", "AiChatCreate", "AiChatDelete", "AiChatUpdate", "UserNotificationsRead", "UserNotificationsUpdate", "UserProfileUpdate" ] }, "PermissionSystemRoles": { "description": "The different system roles that can be assigned.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser" ], "type": "string" }, "PixelValidation": { "properties": { "firing_data_ok": { "description": "False when the event lookup failed, meaning `host_events` and `last_seen_days` are incomplete.", "example": true, "type": "boolean" }, "host_events": { "items": { "description": "Conversion event names detected on the requested page or fired recently anywhere on its hostname or final redirect hostname.", "example": "lead", "type": "string" }, "type": "array" }, "installed": { "description": "Whether the pixel was seen. Without a `url` this answers for the whole account: true when it has sent events recently. With a `url` it answers for THAT page only — true when the page is hosted on Whop, when the page itself has sent events recently, or when the pixel was found in its source. Events the account sent from other pages do not make a given `url` installed.", "example": true, "type": "boolean" }, "last_fired_days": { "description": "Event name to whole days since that event last fired, e.g. `{ \"lead\": 3 }`. Carries events that fired too long ago to count as installed, so you can prompt to re-check rather than report them missing.", "example": { "lead": 2 }, "type": "object" }, "last_seen_days": { "description": "Days since the pixel last sent an event, within a 30-day window. `null` when it hasn't sent one in that window — which includes a pixel installed moments ago.", "example": 2, "type": [ "number", "null" ] }, "native_tracking": { "description": "True when `url` is hosted on Whop, so no pixel snippet is required.", "example": false, "type": "boolean" }, "page_events": { "items": { "description": "Conversion event names detected on the requested page, from its recent events or its source and linked scripts.", "example": "lead", "type": "string" }, "type": "array" }, "reachable": { "description": "Whether the page could be loaded. `null` when the request included no URL, and `true` when events settled the answer without a fetch.", "example": true, "type": [ "boolean", "null" ] }, "url": { "description": "The URL that was checked, after normalization. `null` when the request didn't include one.", "example": "https://shinetime.example/checkout/complete", "type": [ "string", "null" ] } }, "required": [ "installed", "url", "reachable", "last_seen_days", "page_events", "host_events", "native_tracking", "last_fired_days", "firing_data_ok" ], "type": "object" }, "Plan": { "properties": { "account": { "description": "Account that sells this plan; `null` for standalone invoice plans.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this plan. Raw setting — does not check processor compatibility or feature flags.", "example": true, "type": "boolean" }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 30, "type": [ "number", "null" ] }, "cancel_discount_intervals": { "description": "Billing intervals the cancellation discount applies to (`0` forever, `1` first payment, or a month count). `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 3, "type": [ "number", "null" ] }, "cancel_discount_percentage": { "description": "Cancellation discount as a whole-number percentage. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 20, "type": [ "number", "null" ] }, "checkout_styling": { "description": "Plan-level checkout styling (`background_color`, `button_color`, `font_family`, `border_style`); `null` inherits the account default.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "collect_tax": { "description": "Whether tax is collected on purchases of this plan, based on the account's tax configuration.", "example": false, "type": "boolean" }, "created_at": { "description": "When the plan was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for this plan's prices.", "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" ], "example": "usd", "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "deletable": { "description": "Whether the plan can be deleted (it has no memberships or waitlist entries). `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": true, "type": [ "boolean", "null" ] }, "description": { "description": "Customer-visible plan description. Maximum 1000 characters. `null` if no description is set.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout for this plan, resolved through every layer (the plan's own and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays the plan's own editable override.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutSessionPaymentMethodConfiguration" }, { "type": "null" } ] }, "expiration_days": { "description": "Access duration in days for expiration-based plans, such as 365 for a one-year pass. `null` for plans without an expiration.", "example": 365, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval), e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when no image is set.", "example": { "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1", "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial purchase price in plan currency.", "example": 0.0, "type": "number" }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this plan was generated for; `null` unless created for an invoice.", "example": { "id": "inv_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this plan. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "example": { "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether a cancellation discount is offered. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": true, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when plan uses default settings.", "example": { "disabled": [ "crypto" ], "enabled": [ "card" ], "include_platform_defaults": true }, "type": [ "object", "null" ] }, "plan_type": { "description": "Billing model for this plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "product": { "description": "Product this plan belongs to; `null` for standalone plans.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this plan directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period.", "example": 59.0, "type": "number" }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses. Must be greater than 1. `null` if split pay is not configured.", "example": 4, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 99.0, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 79.0, "type": [ "number", "null" ] }, "tax_type": { "description": "How tax is handled for this plan, including whether tax is included in the price, added at checkout, or not configured.", "enum": [ "inclusive", "exclusive", "unspecified" ], "example": "unspecified", "type": "string" }, "three_ds_level": { "description": "3D Secure behavior for this plan; `null` inherits the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "Plan display name shown to customers. Maximum 30 characters. `null` if no title has been set.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge. `null` if no trial is configured or the user has already used a trial for this plan.", "example": 7, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When `true`, the `stock` field is ignored; waitlist plans always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the plan was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this plan can be seen. When `hidden`, the plan is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "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", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "stock", "unlimited_stock", "split_pay_required_payments", "adaptive_pricing_enabled", "strike_through_initial_price", "strike_through_renewal_price", "checkout_styling", "offer_cancel_discount", "cancel_discount_percentage", "cancel_discount_intervals", "payment_method_configuration", "image", "tax_type", "collect_tax", "deletable", "effective_payment_method_configuration", "custom_fields" ], "type": "object" }, "PlanCustomField": { "properties": { "field_type": { "description": "Custom field input type.", "enum": [ "text" ], "example": "text", "type": "string" }, "id": { "description": "Custom field ID, prefixed `field_`.", "example": "field_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Field label shown to customer at checkout.", "example": "Vehicle make and model", "type": "string" }, "order": { "description": "Field position on checkout form.", "example": 0, "type": "number" }, "placeholder": { "description": "Placeholder text shown in the empty field. `null` if none is set.", "example": "2021 Audi S5", "type": [ "string", "null" ] }, "required": { "description": "Whether the customer must complete this field to check out.", "example": true, "type": "boolean" } }, "required": [ "id", "field_type", "name", "order", "placeholder", "required" ], "type": "object" }, "PlanListItem": { "properties": { "account": { "description": "Account that sells this plan; `null` for standalone invoice plans.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this plan. Raw setting — does not check processor compatibility or feature flags.", "example": true, "type": "boolean" }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 30, "type": [ "number", "null" ] }, "cancel_discount_intervals": { "description": "Billing intervals the cancellation discount applies to (`0` forever, `1` first payment, or a month count). `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 3, "type": [ "number", "null" ] }, "cancel_discount_percentage": { "description": "Cancellation discount as a whole-number percentage. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 20, "type": [ "number", "null" ] }, "checkout_styling": { "description": "Plan-level checkout styling (`background_color`, `button_color`, `font_family`, `border_style`); `null` inherits the account default.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "created_at": { "description": "When the plan was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for this plan's prices.", "example": "usd", "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "description": { "description": "Customer-visible plan description. Maximum 1000 characters. `null` if no description is set.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based plans, such as 365 for a one-year pass. `null` for plans without an expiration.", "example": 365, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval), e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when no image is set.", "example": { "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1", "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial purchase price in plan currency.", "example": 0.0, "type": "number" }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this plan was generated for; `null` unless created for an invoice.", "example": { "id": "inv_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this plan. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "example": { "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether a cancellation discount is offered. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": true, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when plan uses default settings.", "example": { "disabled": [ "crypto" ], "enabled": [ "card" ], "include_platform_defaults": true }, "type": [ "object", "null" ] }, "plan_type": { "description": "Billing model for this plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "product": { "description": "Product this plan belongs to; `null` for standalone plans.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this plan directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period.", "example": 59.0, "type": "number" }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses. Must be greater than 1. `null` if split pay is not configured.", "example": 4, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 99.0, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 79.0, "type": [ "number", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this plan; `null` inherits the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "Plan display name shown to customers. Maximum 30 characters. `null` if no title has been set.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge. `null` if no trial is configured or the user has already used a trial for this plan.", "example": 7, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When `true`, the `stock` field is ignored; waitlist plans always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the plan was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this plan can be seen. When `hidden`, the plan is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "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", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "stock", "unlimited_stock", "split_pay_required_payments", "adaptive_pricing_enabled", "strike_through_initial_price", "strike_through_renewal_price", "checkout_styling", "offer_cancel_discount", "cancel_discount_percentage", "cancel_discount_intervals", "payment_method_configuration", "image", "custom_fields" ], "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": { "properties": { "account": { "description": "Account that sells this product.", "example": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "type": [ "object", "null" ] }, "created_at": { "description": "When the product was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_cta": { "description": "Call-to-action button label shown on the product purchase page.", "enum": [ "get_access", "join", "order_now", "shop_now", "call_now", "donate_now", "contact_us", "sign_up", "subscribe", "purchase", "get_offer", "apply_now", "complete_order", null ], "example": "order_now", "type": [ "string", "null" ] }, "custom_cta_url": { "description": "URL the call-to-action button links to instead of checkout.", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "Custom text label on customer's bank statement.", "example": "WHOP*SHINETIME", "type": [ "string", "null" ] }, "default_plan": { "description": "Buyable plan to show and check out with. The configured default when that plan is buyable, otherwise the first buyable plan in product-page order. `null` when none is buyable.", "oneOf": [ { "$ref": "#/components/schemas/ProductPublicPlan" }, { "type": "null" } ] }, "description": { "description": "Written description displayed on the product page. `null` if none is set.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "type": [ "string", "null" ] }, "external_identifier": { "description": "External identifier stored on the product for your own reference.", "example": "SHINE-CERAMIC-01", "type": [ "string", "null" ] }, "gallery_images": { "items": { "$ref": "#/components/schemas/ProductGalleryImage", "description": "Gallery images for this product, ordered by position." }, "type": "array" }, "global_affiliate_percentage": { "description": "Commission rate affiliates earn through the global affiliate program.", "example": 10.0, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Enrollment status in the global affiliate program.", "enum": [ "enabled", "disabled", null ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Short marketing headline displayed on product page.", "example": "Steam, shampoo, and odor removal in one visit", "type": [ "string", "null" ] }, "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "labels": { "items": { "description": "Lowercased labels used to group products into collections. Filter the list endpoint by `labels` to fetch one collection.", "example": "interior", "type": "string" }, "type": "array" }, "marketplace_status": { "description": "Listing state on the whop.com marketplace. `pending_review` means submitted and awaiting review; `live_marketplace` means approved and discoverable.", "enum": [ "not_available", "pending_review", "live_marketplace" ], "example": "not_available", "type": "string" }, "member_affiliate_percentage": { "description": "Commission rate members earn through the member affiliate program.", "example": 5.0, "type": [ "number", "null" ] }, "member_affiliate_status": { "description": "Enrollment status in the member affiliate program.", "enum": [ "enabled", "disabled", null ], "example": "enabled", "type": [ "string", "null" ] }, "member_count": { "description": "Active memberships for this product; 0 if public member counts are disabled.", "example": 0, "type": "number" }, "metadata": { "description": "Custom key-value pairs stored on the product.", "example": { "bay": "1", "duration_hours": "4" }, "type": [ "object", "null" ] }, "owner_user": { "description": "User who owns the account selling this product.", "example": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "type": [ "object", "null" ] }, "product_tax_code": { "description": "Tax classification code for this product, or `null` if no tax code is set.", "example": { "id": "ptc_xxxxxxxxxxxxxx", "name": "General - Digital Goods", "product_type": "digital" }, "type": [ "object", "null" ] }, "published_reviews_count": { "description": "Published customer reviews for this product.", "example": 0, "type": "number" }, "route": { "description": "URL slug for the product's public link.", "example": "interior-deep-clean", "type": "string" }, "title": { "description": "Product display name shown to customers.", "example": "Interior Deep Clean", "type": "string" }, "updated_at": { "description": "When the product was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "verified": { "description": "Whether the product has been verified by Whop.", "example": false, "type": "boolean" }, "visibility": { "description": "Whether the product is publicly visible, hidden, or archived.", "example": "visible", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "updated_at", "title", "visibility", "headline", "description", "verified", "member_count", "route", "published_reviews_count", "external_identifier", "metadata", "labels", "account", "default_plan", "custom_cta", "custom_cta_url", "custom_statement_descriptor", "global_affiliate_percentage", "global_affiliate_status", "member_affiliate_percentage", "member_affiliate_status", "product_tax_code", "owner_user", "marketplace_status", "gallery_images" ], "type": "object" }, "ProductGalleryImage": { "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg.", "example": "image/png", "type": [ "string", "null" ] }, "id": { "description": "Gallery image ID.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "Pre-optimized URL for rendering this image on the client.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "url", "content_type" ], "type": "object" }, "ProductListItem": { "properties": { "account": { "description": "Account that sells this product.", "example": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "type": [ "object", "null" ] }, "created_at": { "description": "When the product was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "default_plan": { "description": "Buyable plan to show and check out with. The configured default when that plan is buyable, otherwise the first buyable plan in product-page order. `null` when none is buyable.", "oneOf": [ { "$ref": "#/components/schemas/ProductPublicPlan" }, { "type": "null" } ] }, "description": { "description": "Written description displayed on the product page. `null` if none is set.", "example": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "type": [ "string", "null" ] }, "external_identifier": { "description": "External identifier stored on the product for your own reference.", "example": "SHINE-CERAMIC-01", "type": [ "string", "null" ] }, "gallery_images": { "items": { "$ref": "#/components/schemas/ProductGalleryImage", "description": "Gallery images for this product, ordered by position." }, "type": "array" }, "headline": { "description": "Short marketing headline displayed on product page.", "example": "A showroom finish that lasts three years", "type": [ "string", "null" ] }, "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "labels": { "items": { "description": "Lowercased labels used to group products into collections. Filter the list endpoint by `labels` to fetch one collection.", "example": "courses", "type": "string" }, "type": "array" }, "member_count": { "description": "Active memberships for this product; 0 if public member counts are disabled.", "example": 0, "type": "number" }, "metadata": { "description": "Custom key-value pairs stored on the product.", "example": {}, "type": [ "object", "null" ] }, "published_reviews_count": { "description": "Published customer reviews for this product.", "example": 0, "type": "number" }, "route": { "description": "URL slug for the product's public link.", "example": "ceramic-coating-package", "type": "string" }, "title": { "description": "Product display name shown to customers.", "example": "Ceramic Coating Package", "type": "string" }, "updated_at": { "description": "When the product was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "verified": { "description": "Whether the product has been verified by Whop.", "example": false, "type": "boolean" }, "visibility": { "description": "Whether the product is publicly visible, hidden, or archived.", "example": "visible", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "updated_at", "title", "visibility", "headline", "description", "verified", "member_count", "route", "published_reviews_count", "external_identifier", "metadata", "labels", "account", "default_plan", "gallery_images" ], "type": "object" }, "ProductPublicPlan": { "properties": { "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 30, "type": [ "number", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based plans. `null` for plans without an expiration.", "type": [ "number", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "$ref": "#/components/schemas/Money", "description": "What checkout charges up front. `amount` is `\"0.00\"` when the first charge is free, such as a trial." }, "plan_type": { "description": "Billing model for this plan: `one_time` or `renewal`.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "renewal_price": { "$ref": "#/components/schemas/Money", "description": "The recurring charge every `billing_period` days. `amount` is `\"0.00\"` for one-time plans." }, "title": { "description": "Plan display name shown to customers. `null` if no title has been set.", "type": [ "string", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock.", "example": true, "type": "boolean" }, "visibility": { "description": "Where this plan can be seen. `visible` plans appear on the product page.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "title", "plan_type", "billing_period", "initial_price", "renewal_price", "visibility", "unlimited_stock", "expiration_days" ], "type": "object" }, "ProductTaxCodeProductTypes": { "description": "The product_type of the ProductTaxCode", "enum": [ "physical", "digital", "services" ], "type": "string" }, "PromoCode": { "properties": { "account": { "$ref": "#/components/schemas/AccountSummary", "description": "Account that owns the promo code." }, "amount_off": { "description": "Discount amount. Percentage discounts are represented as a decimal fraction.", "example": 0.25, "type": "number" }, "churned_users_only": { "description": "Whether the promo code is restricted to churned customers.", "example": false, "type": "boolean" }, "code": { "description": "Code entered at checkout.", "example": "affiliate25", "type": [ "string", "null" ] }, "created_at": { "description": "When the promo code was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for a fixed-amount discount.", "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" ], "example": "usd", "type": "string" }, "duration": { "description": "How long the discount applies.", "enum": [ "forever", "once", "repeating" ], "example": "repeating", "type": "string" }, "existing_memberships_only": { "description": "Whether the promo code applies only to existing memberships.", "example": false, "type": "boolean" }, "expires_at": { "description": "When the promo code expires, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Promo code ID, prefixed `promo_`.", "example": "promo_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata stored on the promo code.", "example": {}, "type": "object" }, "new_users_only": { "description": "Whether the promo code is restricted to new customers.", "example": true, "type": "boolean" }, "one_per_customer": { "description": "Whether each customer may redeem the promo code only once.", "example": true, "type": "boolean" }, "product": { "description": "Product the promo code is restricted to, or `null` when it is not product-scoped.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeProduct" }, { "type": "null" } ] }, "promo_duration_months": { "description": "Billing intervals the discount applies to.", "example": 3, "type": [ "integer", "null" ] }, "promo_type": { "description": "Whether the discount is percentage-based or a fixed amount.", "enum": [ "percentage", "flat_amount" ], "example": "percentage", "type": "string" }, "status": { "description": "Promo code lifecycle status.", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" }, "stock": { "description": "Maximum uses when stock is limited.", "example": 200, "type": "integer" }, "unlimited_stock": { "description": "Whether the promo code has no redemption limit.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the promo code was updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "uses": { "description": "Memberships that used the promo code.", "example": 0, "type": "integer" } }, "required": [ "id", "code", "amount_off", "currency", "promo_type", "duration", "promo_duration_months", "uses", "stock", "status", "expires_at", "created_at", "updated_at", "new_users_only", "churned_users_only", "unlimited_stock", "one_per_customer", "existing_memberships_only", "product", "metadata", "account" ], "type": "object" }, "PromoCodeListItem": { "properties": { "amount_off": { "description": "Discount amount. Percentage discounts are represented as a decimal fraction.", "example": 0.1, "type": "number" }, "churned_users_only": { "description": "Whether the promo code is restricted to churned customers.", "example": false, "type": "boolean" }, "code": { "description": "Code entered at checkout.", "example": "welcome", "type": [ "string", "null" ] }, "created_at": { "description": "When the promo code was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for a fixed-amount discount.", "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" ], "example": "usd", "type": "string" }, "duration": { "description": "How long the discount applies.", "enum": [ "forever", "once", "repeating" ], "example": "repeating", "type": "string" }, "existing_memberships_only": { "description": "Whether the promo code applies only to existing memberships.", "example": false, "type": "boolean" }, "expires_at": { "description": "When the promo code expires, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Promo code ID, prefixed `promo_`.", "example": "promo_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata stored on the promo code.", "example": {}, "type": "object" }, "new_users_only": { "description": "Whether the promo code is restricted to new customers.", "example": true, "type": "boolean" }, "one_per_customer": { "description": "Whether each customer may redeem the promo code only once.", "example": true, "type": "boolean" }, "product": { "description": "Product the promo code is restricted to, or `null` when it is not product-scoped.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeProduct" }, { "type": "null" } ] }, "promo_duration_months": { "description": "Billing intervals the discount applies to.", "example": 1, "type": [ "integer", "null" ] }, "promo_type": { "description": "Whether the discount is percentage-based or a fixed amount.", "enum": [ "percentage", "flat_amount" ], "example": "percentage", "type": "string" }, "status": { "description": "Promo code lifecycle status.", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" }, "stock": { "description": "Maximum uses when stock is limited.", "example": 25, "type": "integer" }, "unlimited_stock": { "description": "Whether the promo code has no redemption limit.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the promo code was updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "uses": { "description": "Memberships that used the promo code.", "example": 1, "type": "integer" } }, "required": [ "id", "code", "amount_off", "currency", "promo_type", "duration", "promo_duration_months", "uses", "stock", "status", "expires_at", "created_at", "updated_at", "new_users_only", "churned_users_only", "unlimited_stock", "one_per_customer", "existing_memberships_only", "product", "metadata" ], "type": "object" }, "PromoCodeProduct": { "properties": { "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Product display name.", "example": "Ceramic Coating Package", "type": "string" } }, "required": [ "id", "title" ], "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" }, "PublicBountySubmission": { "properties": { "bounty_id": { "description": "The bounty the work was submitted to, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "claimed_at": { "description": "When the worker claimed the submission, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "When the submission was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "denial_reason": { "description": "Why the submission was denied, when a presentable reason exists. Always `null` unless `status` is `denied`.", "example": "The wheels were never shown in the finished clip.", "type": [ "string", "null" ] }, "id": { "description": "Submission ID, prefixed `btys_`.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" }, "latest_proof_livestream_feed": { "description": "Latest public proof livestream attached to the submission.", "oneOf": [ { "$ref": "#/components/schemas/BountySubmissionLivestreamFeed" }, { "type": "null" } ] }, "resolved_at": { "description": "When the submission was approved or denied, as an ISO 8601 timestamp. `null` until then.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle state. `submitted` submissions await review; `approved` submissions were accepted and paid; `denied` submissions were rejected. In-progress attempts never appear on the public list.", "enum": [ "submitted", "approved", "denied" ], "example": "approved", "type": "string" }, "submitted_at": { "description": "When proof was submitted for review, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "updated_at": { "description": "When the submission was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "worker": { "$ref": "#/components/schemas/UserSummary", "description": "User who submitted the work." } }, "required": [ "id", "bounty_id", "status", "denial_reason", "claimed_at", "submitted_at", "resolved_at", "latest_proof_livestream_feed", "created_at", "updated_at", "worker" ], "type": "object" }, "ReachEstimate": { "properties": { "users_lower_bound": { "description": "Low end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.", "example": 1500000, "type": [ "number", "null" ] }, "users_upper_bound": { "description": "High end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.", "example": 1800000, "type": [ "number", "null" ] } }, "required": [ "users_lower_bound", "users_upper_bound" ], "type": "object" }, "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", "authorized", "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" }, "RecommendedActionExecution": { "properties": { "action": { "description": "The action definition key the step ran", "example": "create_product", "type": "string" }, "completed_at": { "description": "When the step reached a terminal status, ISO 8601", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "error": { "description": "Why the step failed, or `null`", "type": [ "string", "null" ] }, "id": { "description": "Execution ID, prefixed `raex_`", "example": "raex_xxxxxxxxxxxxxx", "type": "string" }, "output": { "description": "The API response the step produced, or `null` until it succeeds", "example": { "id": "prod_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "position": { "description": "Zero-based order of the step within the chain", "example": 0, "type": "integer" }, "status": { "description": "Where the step currently stands", "enum": [ "pending", "redirected", "running", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "id", "position", "action", "status", "output", "error", "completed_at" ], "type": "object" }, "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. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "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 and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "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" }, "ResolutionAttachment": { "properties": { "content_type": { "description": "The file's MIME type.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "The original file name.", "example": "booking-confirmation.png", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the attachment, prefixed `att_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "A URL to view or download the file.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "ResolutionBuyer": { "properties": { "email": { "description": "The customer's email address. Requires the `member:email:read` scope; `null` without it.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "member_id": { "description": "The customer's member row on the account, prefixed `mem_`.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "name": { "description": "The customer's display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "user_id": { "description": "The customer's user ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "The customer's Whop username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "user_id", "member_id", "name", "username", "email" ], "type": "object" }, "ResolutionCenterCase": { "properties": { "account": { "description": "The account the case was filed against.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "amount": { "description": "The amount in question, in whole units of `currency`.", "example": 249.0, "type": "number" }, "available_actions": { "items": { "description": "What you can do to this case right now, named for the endpoint that does it. Resolved for the calling credential, so a merchant and a customer reading the same case see their own options.", "enum": [ "accept", "deny", "request_info", "reply", "appeal", "withdraw" ], "example": "accept", "type": "string" }, "type": "array" }, "buyer": { "$ref": "#/components/schemas/ResolutionBuyer", "description": "The customer who opened the case." }, "created_at": { "description": "When the case was opened, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the amount.", "example": "usd", "type": [ "string", "null" ] }, "customer_appealed": { "description": "Whether the customer has appealed a decision on this case.", "example": false, "type": "boolean" }, "escalated": { "description": "Whether Whop is involved — either reviewing the case, or waiting on the side named by `status` for something it asked for while reviewing.", "example": false, "type": "boolean" }, "id": { "description": "Resolution center case ID, prefixed `reso_`.", "example": "reso_xxxxxxxxxxxxxx", "type": "string" }, "outcome": { "description": "Who prevailed on the claim. `null` until the case closes. Read `refund` for whether any money actually moved.", "enum": [ "customer_won", "merchant_won", "withdrawn", null ], "example": "merchant_won", "type": [ "string", "null" ] }, "payment": { "$ref": "#/components/schemas/ResolutionPayment", "description": "The payment the case was opened against." }, "plan_id": { "description": "The plan the payment was made on, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "reason": { "description": "What the customer says went wrong. Shares the `/disputes` vocabulary, so a case that later becomes a chargeback reports the same complaint.", "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "product_not_received", "type": "string" }, "refund": { "description": "Whether money moved and off whose balance: `none`, `merchant`, or `platform` (Whop refunded the customer and the merchant kept the funds). Independent of `outcome` — a case the merchant won can still carry a platform refund. `null` while the case is open, and on older closed cases that predate this being recorded.", "enum": [ "none", "merchant", "platform", null ], "example": "none", "type": [ "string", "null" ] }, "response_due_at": { "description": "When the next response is due, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Who the case is waiting on. `awaiting_merchant` and `awaiting_customer` name the side that owes a response, `under_review` means Whop is deciding, and `closed` means it is settled — read `outcome` for how.", "enum": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "example": "closed", "type": "string" }, "updated_at": { "description": "When the case was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "status", "escalated", "outcome", "refund", "reason", "amount", "currency", "account", "product_id", "plan_id", "customer_appealed", "available_actions", "response_due_at", "buyer", "payment", "created_at", "updated_at" ], "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" }, "ResolutionEvent": { "properties": { "action": { "description": "The action recorded in this event.", "enum": [ "created", "responded", "accepted", "denied", "appealed", "withdrew", "requested_more_info", "escalated", "dispute_opened", "dispute_customer_won", "dispute_merchant_won" ], "example": "created", "type": "string" }, "attachments": { "items": { "$ref": "#/components/schemas/ResolutionAttachment", "description": "Files attached to this event, such as screenshots or documents." }, "type": "array" }, "created_at": { "description": "When the event occurred, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "details": { "description": "The message body or additional context provided with the event.", "example": "Booked the Ceramic Coating Package for 2026-01-05; nobody arrived.", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the event, prefixed `revt_`.", "example": "revt_xxxxxxxxxxxxxx", "type": "string" }, "reporter_type": { "description": "The party that performed the action.", "enum": [ "merchant", "customer", "platform", "system" ], "example": "customer", "type": "string" }, "viewable_by_customer": { "description": "Whether the customer can see this event in the timeline.", "example": true, "type": "boolean" }, "viewable_by_merchant": { "description": "Whether the merchant can see this event in the timeline.", "example": true, "type": "boolean" } }, "required": [ "id", "action", "reporter_type", "details", "viewable_by_customer", "viewable_by_merchant", "created_at", "attachments" ], "type": "object" }, "ResolutionPayment": { "properties": { "card_brand": { "description": "Card brand, when the customer paid by card.", "example": "visa", "type": [ "string", "null" ] }, "card_last4": { "description": "Last four digits of the card, when the customer paid by card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was made, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Payment ID, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "description": "How the customer paid, such as `card` or `paypal`.", "example": "card", "type": [ "string", "null" ] } }, "required": [ "id", "payment_method_type", "card_brand", "card_last4", "created_at" ], "type": "object" }, "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", "adds_to_cart", "adds_to_wishlist", "adds_of_payment_info", "checkouts_initiated", "website_schedules", "website_submit_applications", "website_trials_started", "website_subscriptions", "website_contacts", "website_donations", "website_find_locations", "website_product_customizations", "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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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": "URL slug for the account'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": "Uploaded file MIME type, such as image/jpeg, video/mp4, or 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" }, "ScheduleFrequencies": { "description": "How often a scheduled bounty republishes a new bounty.", "enum": [ "once", "hourly", "daily", "weekly", "monthly" ], "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." }, "three_ds_verified": { "description": "Whether 3D Secure authentication was completed when this payment method was set up.", "type": "boolean" } }, "required": [ "id", "status", "created_at", "error_message", "company", "checkout_configuration", "member", "payment_method", "metadata", "three_ds_verified" ], "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" }, "SetupLastSetupError": { "properties": { "code": { "description": "A machine-readable classification of the failure, e.g. `enrollment_declined`. Absent when the buyer simply abandoned the setup.", "example": "enrollment_declined", "type": [ "string", "null" ] }, "message": { "description": "A human-readable explanation of the failure.", "example": "The enrollment was declined by the payment provider.", "type": [ "string", "null" ] } }, "required": [ "code", "message" ], "type": "object" }, "SetupStatus": { "properties": { "id": { "description": "The setup this status describes, prefixed `sint_`.", "example": "sint_xxxxxxxxxxxxxx", "type": "string" }, "last_setup_error": { "description": "Why the setup ended where it did, or `null` when nothing has failed. Present on `canceled` — a buyer who abandoned carries no code, one refused by the provider does.", "oneOf": [ { "$ref": "#/components/schemas/SetupLastSetupError" }, { "type": "null" } ] }, "next_action": { "description": "What the buyer must do next while `status` is `requires_action`, otherwise `null`. `type` picks the shape and each variant carries only its own `data`, so switching on `type` gives you exactly that step's payload.", "oneOf": [ { "$ref": "#/components/schemas/PaymentNextAction" }, { "type": "null" } ] }, "object": { "description": "Always `setup_status`.", "example": "setup_status", "type": "string" }, "return_url": { "description": "Where to send the buyer once the setup reaches a resting state, or `null` to leave them where they are.", "example": "https://shinetime.example/billing/saved", "type": [ "string", "null" ] }, "status": { "description": "How far the setup has got. **A 200 means we answered, not that the method was saved — always branch on this.** `requires_action` — the buyer has a step outstanding; see `next_action`. `processing` — the buyer has done their part and the processor is deciding. `succeeded` — the payment method is saved, and only this one means saved. `canceled` — abandoned or refused; see `last_setup_error` to tell which.", "enum": [ "processing", "succeeded", "canceled", "requires_action" ], "example": "canceled", "type": "string" } }, "required": [ "id", "object", "status", "next_action", "last_setup_error", "return_url" ], "type": "object" }, "Shipment": { "properties": { "account_id": { "description": "The account that owns this shipment, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "carrier": { "description": "The shipping carrier detected for this shipment. Null until a tracking update identifies it.", "example": "ups", "type": [ "string", "null" ] }, "checkpoints": { "items": { "$ref": "#/components/schemas/ShipmentCheckpoint", "description": "Carrier scan history for this shipment, oldest scan first. Empty until the carrier reports its first scan." }, "type": "array" }, "created_at": { "description": "The datetime the shipment was created (ISO 8601).", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Shipment ID, prefixed `ship_`.", "example": "ship_xxxxxxxxxxxxxx", "type": "string" }, "payment_id": { "description": "The payment this shipment fulfills, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "The current delivery status of this shipment.", "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "example": "in_transit", "type": "string" }, "tracking_number": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "1Z999AA10123456784", "type": "string" }, "tracking_url": { "description": "A customer-facing URL to track this shipment's progress.", "example": "https://track.aftership.com/xxxxxxxxxxxxxxxxxx", "type": "string" }, "updated_at": { "description": "The datetime the shipment was last updated (ISO 8601).", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "status", "tracking_number", "carrier", "tracking_url", "checkpoints", "payment_id", "created_at", "updated_at" ], "type": "object" }, "ShipmentCheckpoint": { "properties": { "location": { "description": "Where the carrier recorded the scan, such as `PHILADELPHIA, PA`. Null when the carrier sent none.", "example": "PHILADELPHIA, PA", "type": [ "string", "null" ] }, "message": { "description": "Carrier's description of the scan, such as `Departed USPS Regional Facility`. Null when the carrier sent none.", "example": "Picked up", "type": [ "string", "null" ] }, "status": { "description": "Delivery status this carrier scan maps to.", "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "example": "in_transit", "type": "string" }, "timestamp": { "description": "When the carrier recorded the scan, as an ISO 8601 timestamp. Null when the carrier sent no scan time.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "status", "message", "location", "timestamp" ], "type": "object" }, "ShipmentListItem": { "description": "A physical shipment associated with a payment, including carrier details and tracking information.", "properties": { "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", "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" }, "SocialAccount": { "properties": { "error": { "description": "Why this social account currently can't be used for advertising — a failed share or a Meta-side restriction. Null when the account is healthy.", "example": "You don't have permission to share this account. Ask an admin of its Meta Business Portfolio to grant you full control, then share it again.", "type": [ "string", "null" ] }, "external_id": { "description": "The platform-specific ID for this social account.", "example": "1234567891", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the social account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the social account on the platform.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "parent_social_account": { "description": "The social account this one belongs to on the platform, such as the Facebook page that owns an Instagram account. Null when the social account stands on its own.", "oneOf": [ { "$ref": "#/components/schemas/SocialAccountParent" }, { "type": "null" } ] }, "platform": { "description": "The platform the social account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram" ], "example": "instagram", "type": "string" }, "profile_picture_url": { "description": "The URL where the profile picture of the social account can be accessed.", "example": "https://shinetime.example/logo.png", "type": [ "string", "null" ] }, "scopes": { "items": { "description": "Capabilities Whop retains specific to this social account. For example, Whop may request the ability to run advertisements that use this social account's identity, reflected by the presence of `advertise` in this value.", "example": "advertise", "type": "string" }, "type": "array" }, "url": { "description": "The URL where the social account can be accessed on the platform. Null while a Whop-owned page is still being provisioned.", "example": "https://instagram.com/shinetimedetail", "type": [ "string", "null" ] }, "username": { "description": "The username of the social account on the platform. Null while a Whop-owned page is still being provisioned.", "example": "shinetimedetail", "type": [ "string", "null" ] }, "verified": { "description": "Whether the social account is verified on the platform.", "example": true, "type": "boolean" } }, "required": [ "id", "platform", "username", "name", "url", "profile_picture_url", "verified", "external_id", "scopes", "error", "parent_social_account" ], "type": "object" }, "SocialAccountLeadForm": { "properties": { "completion": { "description": "Screen shown after the form is submitted. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormCompletion" }, { "type": "null" } ] }, "created_at": { "description": "When the form was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disclaimer": { "description": "Custom consent disclaimer shown before submission. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormDisclaimer" }, { "type": "null" } ] }, "form_type": { "description": "`more_volume` is quickest to submit; `higher_intent` adds a confirmation step before submission.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "id": { "description": "The ad platform's identifier for the form. Use it as lead_gen_form_id on an ad to reuse the form.", "example": "24839", "type": "string" }, "intro": { "description": "Intro screen shown before the questions. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormIntro" }, { "type": "null" } ] }, "locale": { "description": "Language the form is shown in, such as en_US.", "example": "en_US", "type": [ "string", "null" ] }, "name": { "description": "Advertiser-facing form name.", "example": "Ceramic coating quote requests", "type": [ "string", "null" ] }, "privacy_policy_link_text": { "description": "Custom link text for the privacy policy. `null` when the default is used.", "example": "Shine Time privacy policy", "type": [ "string", "null" ] }, "privacy_policy_url": { "description": "Privacy policy URL configured on the form.", "example": "https://shinetime.example/privacy", "type": [ "string", "null" ] }, "question_labels": { "items": { "description": "Labels of the questions the form asks, for preview.", "example": "Email", "type": "string" }, "type": "array" }, "questions": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestion", "description": "Questions on the form, in order." }, "type": "array" } }, "required": [ "id", "name", "locale", "created_at", "form_type", "privacy_policy_url", "privacy_policy_link_text", "question_labels", "questions", "intro", "completion", "disclaimer" ], "type": "object" }, "SocialAccountParent": { "properties": { "external_id": { "description": "The platform-specific ID for the parent social account.", "example": "555111", "type": [ "string", "null" ] }, "id": { "description": "Social account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the parent social account on the platform.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "platform": { "description": "The platform the parent social account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram" ], "example": "facebook", "type": "string" }, "profile_picture_url": { "description": "The URL where the profile picture of the parent social account can be accessed.", "example": "https://shinetime.example/logo.png", "type": [ "string", "null" ] }, "username": { "description": "The username of the parent social account on the platform.", "example": "shinetimedetailing", "type": [ "string", "null" ] }, "verified": { "description": "Whether the parent social account is verified on the platform.", "example": true, "type": "boolean" } }, "required": [ "id", "platform", "username", "name", "profile_picture_url", "verified", "external_id" ], "type": "object" }, "SocialAccountPost": { "properties": { "call_to_action": { "description": "The post's call-to-action button, for example shop_now (Facebook only; null for Instagram and TikTok).", "enum": [ "learn_more", "shop_now", "sign_up", "subscribe", "get_started", "book_now", "apply_now", "contact_us", "download", "order_now", "buy_now", "get_quote", "message_page", "whatsapp_message", "instagram_message", "call_now", "get_directions", "send_updates", "get_offer", "watch_more", "listen_now", "play_game", "open_link", "no_button", "get_offer_view", "get_event_tickets", "see_menu", "request_time", "event_rsvp", "see_details", "view_instagram_profile", null ], "example": "shop_now", "type": [ "string", "null" ] }, "destination_url": { "description": "The URL the post's call-to-action drives to (Facebook only; null for Instagram and TikTok).", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "embed_url": { "description": "An iframe-embeddable URL for previewing the post inline (the platform's player or post embed). For TikTok this is the only preview, since media_url is null; for Facebook and Instagram it supplements media_url. Null when no public embed is available.", "example": "https://www.facebook.com/plugins/post.php", "type": [ "string", "null" ] }, "id": { "description": "The platform's own identifier for the post or media. Use it to reference the post on an ad.", "example": "media_1", "type": "string" }, "media_url": { "description": "The URL of the post's media — the image for image posts, the playable video file for video posts. Null for TikTok, which exposes no raw file (use embed_url). Meta URLs are signed and expire after roughly 24 hours, so don't store them.", "example": "https://shinetime.example/ceramic-coating-reel.mp4", "type": [ "string", "null" ] }, "restrictions": { "items": { "description": "Ways this post can't be used on an ad. `lead_form_ineligible`: post can't be used in lead form ads. `promotion_ineligible`: the platform won't promote this post at all — always present when that's true, alongside a reason code when one is identified. `copyrighted_music`: post uses music the platform does not allow for ads. `messenger_destination`, `instagram_destination`, `whatsapp_destination`: the post's own button opens that chat app, so the post can only run in an ad group that sends people to the same one — always accompanied by `lead_form_ineligible`. Empty when the post has no restrictions.", "enum": [ "lead_form_ineligible", "promotion_ineligible", "copyrighted_music", "messenger_destination", "instagram_destination", "whatsapp_destination" ], "example": "lead_form_ineligible", "type": "string" }, "type": "array" }, "thumbnail_url": { "description": "Poster image for video posts (always set for TikTok, which is video-only); null for image posts, where media_url is already the image.", "example": "https://shinetime.example/ceramic-coating-poster.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "media_url", "thumbnail_url", "embed_url", "call_to_action", "destination_url", "restrictions" ], "type": "object" }, "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", "high_risk_merchant_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", "scheduled" ], "type": "string" }, "StorefrontAccount": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL. `null` when the account has not set one.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Account public route identifier — the `whop.com/{route}` storefront path.", "example": "shine-time-auto-detailing", "type": "string" }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "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" }, "TargetingOption": { "description": "One result from the ad-group targeting-options search. `type` picks the shape: detailed-targeting taxonomy options carry the ad platform's `id`, languages carry an ISO 639 `code`, and locations carry the platform `key` plus geographic context.", "discriminator": { "mapping": { "behaviors": "#/components/schemas/DetailedTargetingOption", "education_majors": "#/components/schemas/DetailedTargetingOption", "education_schools": "#/components/schemas/DetailedTargetingOption", "family_statuses": "#/components/schemas/DetailedTargetingOption", "income": "#/components/schemas/DetailedTargetingOption", "industries": "#/components/schemas/DetailedTargetingOption", "interests": "#/components/schemas/DetailedTargetingOption", "languages": "#/components/schemas/LanguageTargetingOption", "life_events": "#/components/schemas/DetailedTargetingOption", "locations": "#/components/schemas/LocationTargetingOption", "work_employers": "#/components/schemas/DetailedTargetingOption", "work_positions": "#/components/schemas/DetailedTargetingOption" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/DetailedTargetingOption" }, { "$ref": "#/components/schemas/LanguageTargetingOption" }, { "$ref": "#/components/schemas/LocationTargetingOption" } ] }, "TaxIdentifierTypes": { "description": "The type of tax identifier", "enum": [ "ad_nrt", "ao_tin", "ar_cuit", "al_tin", "am_tin", "aw_tin", "au_abn", "au_arn", "eu_vat", "az_tin", "bs_tin", "bh_vat", "bd_bin", "bb_tin", "by_tin", "bj_ifu", "bo_tin", "ba_tin", "br_cnpj", "br_cpf", "bg_uic", "bf_ifu", "kh_tin", "cm_niu", "ca_bn", "ca_gst_hst", "ca_pst_bc", "ca_pst_mb", "ca_pst_sk", "ca_qst", "cv_nif", "cl_tin", "cn_tin", "co_nit", "cd_nif", "cr_tin", "hr_oib", "do_rcn", "ec_ruc", "eg_tin", "sv_nit", "et_tin", "eu_oss_vat", "ge_vat", "gh_tin", "de_stn", "gb_vat", "gn_nif", "hk_br", "hu_tin", "is_vat", "in_gst", "id_npwp", "il_vat", "jp_cn", "jp_rn", "jp_trn", "kz_bin", "ke_pin", "kg_tin", "la_tin", "li_uid", "li_vat", "my_frp", "my_itn", "my_sst", "mr_nif", "mx_rfc", "md_vat", "me_pib", "ma_vat", "np_pan", "nz_gst", "ng_tin", "mk_vat", "no_vat", "no_voec", "om_vat", "pe_ruc", "ph_tin", "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" }, "TeamMember": { "properties": { "account_id": { "description": "The account this membership belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "authorized_role": { "description": "Custom role assigned to this member, or `null` when the member has a system role.", "oneOf": [ { "$ref": "#/components/schemas/TeamMemberAuthorizedRole" }, { "type": "null" } ] }, "created_at": { "description": "When the member joined or the invite was sent, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "email": { "description": "The member's email address. For accepted members, `null` unless the caller holds the email read scope; for invites, the invited address.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "Team member ID — `ausr_` for accepted members, `ausri_` for pending invites.", "example": "ausr_xxxxxxxxxxxxxx", "type": "string" }, "is_agent": { "description": "Whether this member is an agent (app-controlled account) rather than a human team member. Always `false` for invites.", "example": false, "type": "boolean" }, "role": { "description": "The member's role on the account. `custom` means a bespoke dashboard-managed role; the API can read but not grant it.", "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "example": "moderator", "type": "string" }, "status": { "description": "`joined` for accepted members, `pending` while the invite is pending.", "enum": [ "joined", "pending" ], "example": "joined", "type": "string" }, "updated_at": { "description": "When the membership was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "description": "The user behind this team membership. `null` for an invite sent to an email with no Whop account yet.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] } }, "required": [ "id", "status", "role", "is_agent", "account_id", "email", "created_at", "updated_at", "authorized_role", "user" ], "type": "object" }, "TeamMemberAuthorizedRole": { "properties": { "id": { "description": "Custom role ID, prefixed `aurl_`.", "type": "string" }, "name": { "description": "Custom role name.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "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" }, "UploadStatuses": { "description": "The upload status of a file", "enum": [ "pending", "processing", "ready", "failed" ], "type": "string" }, "User": { "properties": { "balance": { "description": "The user's balance: personal cash + crypto + in-flight treasury deposits, plus account balances for accounts they own. Computed only on the self view (retrieved with the reserved id `me`) for callers with balance-read scope; `null` otherwise.", "oneOf": [ { "$ref": "#/components/schemas/UserBalance" }, { "type": "null" } ] }, "balance_history": { "description": "The user's cumulative wallet balance over time (USD `{ t, v }` points plus last/min/max), for the balance chart. Opt in with `include_balance_history=true` when retrieving yourself with the reserved id `me`; populated only for callers with balance-read scope and `null` otherwise. A user with no wallet activity returns an empty series.", "oneOf": [ { "$ref": "#/components/schemas/UserBalanceHistory" }, { "type": "null" } ] }, "banner": { "description": "The user's profile banner wrapper. `null` when the user has no banner.", "oneOf": [ { "$ref": "#/components/schemas/UserBanner" }, { "type": "null" } ] }, "bio": { "description": "The user's biography", "example": "Ceramic coating specialist. Detailing cars in Austin since 2016.", "type": [ "string", "null" ] }, "created_at": { "description": "When the user was created, as an ISO 8601 timestamp", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "earnings_usd": { "description": "The user's gross USD income over time. Populated only on single-user self reads for callers with balance-read scope; `null` otherwise.", "oneOf": [ { "$ref": "#/components/schemas/UserEarnings" }, { "type": "null" } ] }, "email": { "description": "The user's email address. Populated only on the self view (retrieved with the reserved id `me`) for callers with email-read scope; `null` otherwise, or while the account has no confirmed email yet.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "$ref": "#/components/schemas/UserProfilePicture", "description": "Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture." }, "social_accounts": { "items": { "$ref": "#/components/schemas/SocialAccount", "description": "Social accounts linked to the user (Discord, X/Twitter, Telegram), oldest first. Reading your own profile returns every linked account; other profiles only include what is public on Whop (the primary Discord and the X account). Empty when none are linked." }, "type": "array" }, "staff": { "description": "Whop staff access flags. Populated only on the self view (retrieved with the reserved id `me`) for callers with staff-read scope; `null` there for every user who is not Whop staff, and always `null` elsewhere.", "oneOf": [ { "$ref": "#/components/schemas/UserStaffAccess" }, { "type": "null" } ] }, "username": { "description": "The user's unique username", "example": "marcuswebb", "type": "string" }, "verification": { "description": "Identity verification status for the user's `individual` (KYC) and `business` (KYB) profiles. Each is `null` until created, otherwise a `status` of `not_started`, `pending`, `approved`, or `rejected`.", "example": { "business": null, "individual": null }, "type": "object" }, "whop_partner_enabled_at": { "description": "When the user became an enrolled Whop Partner, as an ISO 8601 timestamp. `null` if never enrolled.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "id", "username", "name", "bio", "created_at", "profile_picture", "banner", "social_accounts", "email", "staff", "balance", "earnings_usd", "balance_history", "verification", "whop_partner_enabled_at" ], "type": "object" }, "UserBalance": { "properties": { "businesses": { "items": { "$ref": "#/components/schemas/UserBalanceBusiness", "description": "Account balances for accounts the user owns, highest balance first. Excludes accounts with no balance." }, "type": "array" }, "businesses_total_usd": { "description": "Combined USD balance across every account the user owns.", "example": "18940.25", "type": "string" }, "cash": { "items": { "$ref": "#/components/schemas/UserBalanceCash", "description": "Per-currency fiat cash balances." }, "type": "array" }, "cash_usd": { "description": "Fiat cash in USD, including pending, in-transit, and reserve.", "example": "0.00", "type": "string" }, "crypto": { "items": { "$ref": "#/components/schemas/UserBalanceToken", "description": "Per-token crypto holdings in the ledger's own wallet." }, "type": "array" }, "crypto_usd": { "description": "Crypto holdings in USD.", "example": "0.00", "type": "string" }, "pending_usd": { "description": "Fiat pending and in-transit balances, plus in-flight treasury deposits, in USD.", "example": "0.00", "type": "string" }, "total_usd": { "description": "The user's personal balance in USD: cash (available + pending + in-transit + reserve) + crypto + in-flight treasury deposits. Excludes account balances (see businesses_total_usd).", "example": "0.00", "type": "string" }, "treasury_pending_usd": { "description": "Balance-to-wallet USDT0 payouts still in flight, in USD.", "example": "0.00", "type": "string" } }, "required": [ "total_usd", "cash_usd", "crypto_usd", "treasury_pending_usd", "pending_usd", "cash", "crypto", "businesses_total_usd", "businesses" ], "type": "object" }, "UserBalanceBusiness": { "properties": { "balance_usd": { "description": "The account's total balance in USD.", "example": "18940.25", "type": "string" }, "id": { "description": "The account ID, which looks like biz_*************.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "The account's logo URL.", "example": "https://assets.whop.com/logos/shine-time-auto-detailing.png", "type": [ "string", "null" ] }, "name": { "description": "The account's display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "id", "name", "logo_url", "balance_usd" ], "type": "object" }, "UserBalanceCash": { "properties": { "balance": { "description": "Available balance in the native currency.", "example": 4385.75, "type": "number" }, "balance_usd": { "description": "Available balance converted to USD.", "example": 4385.75, "type": "number" }, "currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`.", "example": "usd", "type": "string" }, "in_transit_balance_usd": { "description": "Balance moving to the user's own wallet or card, converted to USD.", "example": 0.0, "type": "number" }, "pending_balance_usd": { "description": "Pending balance converted to USD.", "example": 310.0, "type": "number" }, "price_usd": { "description": "USD price per native currency unit, or `null` when no exchange rate is available.", "type": [ "number", "null" ] }, "reserve_balance_usd": { "description": "Reserved balance converted to USD.", "example": 125.0, "type": "number" }, "total_withdrawable_balance": { "description": "Withdrawable amount in the native currency.", "example": 4385.75, "type": "number" } }, "required": [ "currency", "balance", "balance_usd", "pending_balance_usd", "in_transit_balance_usd", "reserve_balance_usd", "price_usd", "total_withdrawable_balance" ], "type": "object" }, "UserBalanceHistory": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserBalanceHistoryPoint", "description": "Cumulative balance points over the requested window, oldest first." }, "type": "array" }, "last": { "description": "Value of the most recent point, in USD.", "example": 0.0, "type": "number" }, "max": { "description": "Maximum value across the window, in USD.", "example": 0.0, "type": "number" }, "min": { "description": "Minimum value across the window, in USD.", "example": 0.0, "type": "number" } }, "required": [ "data", "last", "min", "max" ], "type": "object" }, "UserBalanceHistoryPoint": { "properties": { "t": { "description": "Point timestamp, in Unix seconds.", "example": 1767268800, "type": "integer" }, "v": { "description": "Cumulative wallet balance at this point, in USD.", "example": 2400.0, "type": "number" } }, "required": [ "t", "v" ], "type": "object" }, "UserBalanceToken": { "properties": { "balance": { "description": "Amount held in native token units, as a decimal string.", "example": "1500.0", "type": "string" }, "breakdown": { "$ref": "#/components/schemas/AccountBalanceBreakdown", "description": "Balance split into available, pending, in-transit, and reserve amounts, as native-unit decimal strings. Transfers between the user's own wallet and card are reported in `in_transit` until they arrive." }, "icon_url": { "description": "Token icon URL.", "example": "https://assets.whop.com/tokens/usdt.png", "type": [ "string", "null" ] }, "name": { "description": "The token's display name.", "example": "Tether USD", "type": [ "string", "null" ] }, "price_usd": { "description": "USD price per token, or `null` when unknown.", "example": 1.0, "type": [ "number", "null" ] }, "symbol": { "description": "Token display symbol, such as `USDT`, `XAUT`, or `cbBTC`.", "example": "USDT", "type": "string" }, "value_usd": { "description": "Holding USD value.", "example": 1500.0, "type": "number" } }, "required": [ "symbol", "name", "balance", "value_usd", "price_usd", "icon_url", "breakdown" ], "type": "object" }, "UserBanner": { "properties": { "url": { "description": "Profile banner image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "url" ], "type": "object" }, "UserEarnings": { "properties": { "first_earned_at": { "description": "The first time the user earned gross income, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "owned_accounts": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Gross income from accounts the user owns or is owner-authorized on." }, "personal": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Gross income from the user's personal wallet." }, "total": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Gross income from the user's personal wallet plus accounts they own or are owner-authorized on." } }, "required": [ "total", "personal", "owned_accounts", "first_earned_at" ], "type": "object" }, "UserEarningsAmount": { "properties": { "last_24_hours": { "description": "Gross income in USD over the last 24 hours.", "example": "0.00", "type": "string" }, "last_30_days": { "description": "Gross income in USD over the last 30 days.", "example": "260.00", "type": "string" }, "last_7_days": { "description": "Gross income in USD over the last 7 days.", "example": "60.00", "type": "string" }, "lifetime": { "description": "All-time gross income in USD.", "example": "4120.25", "type": "string" } }, "required": [ "lifetime", "last_30_days", "last_7_days", "last_24_hours" ], "type": "object" }, "UserNotificationPreference": { "properties": { "created_at": { "description": "When the preference was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Notification preference ID, prefixed `unpf_`.", "example": "unpf_xxxxxxxxxxxxxx", "type": "string" }, "level": { "description": "What the user is notified about in this scope: `all` or `nothing`.", "enum": [ "all", "nothing" ], "example": "all", "type": "string" }, "object": { "description": "The type of object. Always `notification_preference`.", "enum": [ "notification_preference" ], "example": "notification_preference", "type": "string" }, "scope": { "$ref": "#/components/schemas/NotificationPreferenceScope", "description": "What the preference applies to. Echo it back to `PATCH /users/me/preferences/notifications` to change this preference." }, "updated_at": { "description": "When the preference was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "object", "id", "scope", "level", "created_at", "updated_at" ], "type": "object" }, "UserPreferences": { "properties": { "bounty_worker_onboarding_dismissed": { "description": "Whether the user has dismissed the first-time bounty worker onboarding. Set to `false` to show it again.", "example": false, "type": "boolean" }, "investigation_enabled": { "description": "Whether investigation mode is enabled for the user. Only meaningful for staff users with investigation access.", "example": true, "type": "boolean" }, "terms_accepted": { "description": "Whether the user has accepted Whop's terms and policies. `false` until recorded via `PATCH` with `terms_accepted: true`.", "example": true, "type": "boolean" }, "terms_accepted_at": { "description": "When the user most recently accepted Whop's terms and policies, as an ISO 8601 timestamp. `null` until accepted.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "investigation_enabled", "bounty_worker_onboarding_dismissed", "terms_accepted", "terms_accepted_at" ], "type": "object" }, "UserProfilePicture": { "properties": { "url": { "description": "Avatar image URL. Always present — a generated placeholder when the user set no picture.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "UserRecommendedAction": { "properties": { "account_id": { "description": "The account (`biz_`) a business recommendation is for, or `null` for personal recommendations", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "account_name": { "description": "The account's display name, or `null`", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "action": { "description": "The recommendation; new values may be added, so handle unknown actions gracefully", "enum": [ "create_business", "become_affiliate", "become_whop_partner", "theme_business", "create_product", "create_plan", "verify_identity", "connect_affiliate_program", "create_promotion", "migrate_from_stripe", "accept_first_payment", "launch_first_ad", "launch_draft_campaign", "increase_ad_budget", "refresh_ad_creatives", "fix_ad_billing", "exclude_customers_from_ads", "retarget_abandoned_checkouts", "fix_funnel_dropoff", "invite_team_member", "enable_tax_collection", "create_card", "apply_for_financing" ], "example": "apply_for_financing", "type": "string" }, "blocked_capabilities": { "items": { "description": "Capabilities this would unlock, or empty", "example": "accept_bnpl_payments", "type": "string" }, "type": "array" }, "cta": { "description": "The URL the call-to-action links to", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/settings/payments/", "type": "string" }, "cta_label": { "description": "Button label", "example": "Apply", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Let detailing customers split a $249 ceramic coating over four payments.", "type": "string" }, "icon_url": { "description": "Illustration icon URL, or `null`", "example": "https://whop.com/illustrations/orange/piggy-bank.svg", "type": [ "string", "null" ] }, "impact_score": { "description": "Estimated impact from 0-100, or `null` when not ranked", "example": 82, "type": [ "integer", "null" ] }, "reasoning": { "description": "Why this action was recommended, or `null`", "example": "Ceramic coating is the priciest job on the menu, so financing lifts conversion most.", "type": [ "string", "null" ] }, "status": { "description": "Always optional — never blocking", "enum": [ "optional" ], "example": "optional", "type": "string" }, "title": { "description": "Headline for the recommendation", "example": "Offer financing at checkout", "type": "string" } }, "required": [ "action", "status", "title", "description", "cta_label", "cta", "icon_url", "blocked_capabilities", "reasoning", "impact_score", "account_id", "account_name" ], "type": "object" }, "UserStaffAccess": { "properties": { "admin": { "description": "Whether the user holds the admin staff role with a valid second factor.", "example": true, "type": "boolean" }, "investigation_access": { "description": "Whether the user can open Whop-internal investigation tooling right now: a qualifying staff role plus their investigation toggle switched on.", "example": true, "type": "boolean" }, "manager": { "description": "Whether the user holds the manager staff role with a valid second factor.", "example": false, "type": "boolean" }, "support": { "description": "Whether the user holds the support staff role with a valid second factor.", "example": false, "type": "boolean" } }, "required": [ "admin", "support", "manager", "investigation_access" ], "type": "object" }, "UserSummary": { "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "profile_picture": { "$ref": "#/components/schemas/UserProfilePicture", "description": "Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture." }, "username": { "description": "Public username.", "example": "danawhitfield", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": "object" }, "V1ErrorResponse": { "properties": { "error": { "properties": { "code": { "description": "Machine-readable reason for this specific refusal, such as `bank_warning_not_acknowledged`. Only present when the error carries one.", "type": "string" }, "message": { "description": "Human-readable error message.", "example": "account_id is required", "type": "string" }, "type": { "description": "Machine-readable error code.", "example": "bad_request", "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", "manual_review" ], "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": { "properties": { "api_version": { "description": "The API version used to format payloads sent to this webhook endpoint.", "enum": [ "v1", "v2", "v5" ], "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) that v1 payloads for this endpoint are pinned to: events serialize exactly like a REST read at this version (the native serializer where the resource has one). Null when unpinned — legacy (v2/v5) webhooks, and v1 webhooks on the legacy payload shape.", "example": "2026-08-25-2", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on an account, enabling this sends events only from its connected accounts.", "example": false, "type": "boolean" }, "consecutive_failures": { "description": "Number of consecutive deliveries whose first attempt to this endpoint failed since it last accepted one. Later retries of the same delivery do not increment it. Resets to `0` when a delivery succeeds or the webhook is re-enabled.", "example": 9, "type": "integer" }, "created_at": { "description": "When the webhook was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "disabled_at": { "description": "When Whop automatically disabled this webhook, as an ISO 8601 timestamp. `null` unless the webhook was disabled by Whop; a webhook you disabled yourself has `enabled: false` and a `null` `disabled_at`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disabled_reason": { "description": "Why Whop disabled this webhook. `delivery_failures` means every delivery failed for 3 days straight. `null` when `disabled_at` is `null`.", "enum": [ "delivery_failures", null ], "example": "delivery_failures", "type": [ "string", "null" ] }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "example": false, "type": "boolean" }, "events": { "items": { "description": "Event types this webhook is subscribed to, in dot form (for example `payment.succeeded`).", "enum": [ "account.updated", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "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", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "ad_campaign.payment_failed", "chat.message.created", "chat.reaction.created", "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", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" }, "failing_since": { "description": "When the current failure streak began, as an ISO 8601 timestamp. Unlike `last_failure_at`, this is set on the streak's first failed attempt, so it shows an endpoint that is failing right now. `null` when the endpoint is healthy.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Webhook ID, prefixed `hook_`.", "example": "hook_xxxxxxxxxxxxxx", "type": "string" }, "last_failure_at": { "description": "When a delivery to this endpoint most recently failed after exhausting retries, as an ISO 8601 timestamp. `null` if no delivery has ever failed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "resource_id": { "description": "ID of the resource (account or app) this webhook is attached to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "testable_events": { "items": { "description": "The subset of subscribed event types that support sending test payloads, in dot form.", "enum": [ "account.updated", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "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", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "ad_campaign.payment_failed", "chat.message.created", "chat.reaction.created", "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", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_membership.cancel_at_period_end_changed" ], "example": "account.updated", "type": "string" }, "type": "array" }, "url": { "description": "Destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/hooks", "type": "string" }, "webhook_secret": { "description": "Secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic. Returned on the create response and to interactive dashboard sessions; `null` for API-key and OAuth callers on later reads.", "example": "ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "url", "enabled", "events", "api_version", "api_version_date", "created_at", "child_resource_events", "webhook_secret", "resource_id", "consecutive_failures", "failing_since", "last_failure_at", "disabled_at", "disabled_reason", "testable_events" ], "type": "object" }, "WebhookDelivery": { "properties": { "event": { "description": "The event type this delivery carried, for example `payment.succeeded`.", "example": "payment.succeeded", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for this delivery attempt. Pass it to the replay endpoint to re-send this exact payload.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "replayed_from": { "description": "The id of the delivery attempt this one replayed. `null` for an original delivery.", "example": "whdel_MTcwMDAwMDAwMDAwMHx0ZXN0", "type": [ "string", "null" ] }, "request_body": { "description": "The JSON event payload sent to the webhook endpoint.", "example": { "data": { "id": "pay_123" }, "id": "msg_original", "type": "payment.succeeded" }, "type": "object" }, "resource_id": { "description": "ID of the resource that triggered the webhook.", "example": "pay_123", "type": "string" }, "response_body": { "description": "The endpoint's JSON response. A non-JSON response is stored as `{ error, raw_body }` with the first 100 bytes.", "example": { "ok": true }, "type": [ "object", "null" ] }, "response_code": { "description": "HTTP response code received from the webhook endpoint.", "example": 200, "type": "number" }, "sent_at": { "description": "When the webhook was sent, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "success": { "description": "Whether the endpoint acknowledged this attempt with a 2xx response.", "example": true, "type": "boolean" }, "total_time": { "description": "Total time taken to send the webhook request, in seconds.", "example": 0.31, "type": "number" } }, "required": [ "id", "event", "replayed_from", "request_body", "resource_id", "response_body", "response_code", "sent_at", "success", "total_time" ], "type": "object" }, "WebhookEvent": { "description": "The different event types available", "enum": [ "account.updated", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "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", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "ad_campaign.payment_failed", "chat.message.created", "chat.reaction.created", "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": { "properties": { "api_version": { "description": "The API version used to format payloads sent to this webhook endpoint.", "enum": [ "v1", "v2", "v5" ], "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) that v1 payloads for this endpoint are pinned to: events serialize exactly like a REST read at this version (the native serializer where the resource has one). Null when unpinned — legacy (v2/v5) webhooks, and v1 webhooks on the legacy payload shape.", "example": "2026-08-25-2", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on an account, enabling this sends events only from its connected accounts.", "example": false, "type": "boolean" }, "consecutive_failures": { "description": "Number of consecutive deliveries whose first attempt to this endpoint failed since it last accepted one. Later retries of the same delivery do not increment it. Resets to `0` when a delivery succeeds or the webhook is re-enabled.", "example": 0, "type": "integer" }, "created_at": { "description": "When the webhook was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "disabled_at": { "description": "When Whop automatically disabled this webhook, as an ISO 8601 timestamp. `null` unless the webhook was disabled by Whop; a webhook you disabled yourself has `enabled: false` and a `null` `disabled_at`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disabled_reason": { "description": "Why Whop disabled this webhook. `delivery_failures` means every delivery failed for 3 days straight. `null` when `disabled_at` is `null`.", "enum": [ "delivery_failures", null ], "example": "delivery_failures", "type": [ "string", "null" ] }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "example": false, "type": "boolean" }, "events": { "items": { "description": "Event types this webhook is subscribed to, in dot form (for example `payment.succeeded`).", "enum": [ "account.updated", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "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", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "ad_campaign.payment_failed", "chat.message.created", "chat.reaction.created", "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", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" }, "failing_since": { "description": "When the current failure streak began, as an ISO 8601 timestamp. Unlike `last_failure_at`, this is set on the streak's first failed attempt, so it shows an endpoint that is failing right now. `null` when the endpoint is healthy.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Webhook ID, prefixed `hook_`.", "example": "hook_xxxxxxxxxxxxxx", "type": "string" }, "last_failure_at": { "description": "When a delivery to this endpoint most recently failed after exhausting retries, as an ISO 8601 timestamp. `null` if no delivery has ever failed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "resource_id": { "description": "ID of the resource (account or app) this webhook is attached to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "Destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/shine-time/whop", "type": "string" }, "webhook_secret": { "description": "Secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic. Returned on the create response and to interactive dashboard sessions; `null` for API-key and OAuth callers on later reads.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "url", "enabled", "events", "api_version", "api_version_date", "created_at", "child_resource_events", "webhook_secret", "resource_id", "consecutive_failures", "failing_since", "last_failure_at", "disabled_at", "disabled_reason" ], "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" }, "WorkforceBounty": { "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" }, "WorkforceBountyListItem": { "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" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "auth-scheme", "description": "An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with `Bearer`, for example `Bearer ***************************`.", "scheme": "bearer", "type": "http" }, "scopedSessionCookie": { "description": "The scoped session credential a session-intent verify installs on first-party (whop.com) pages — HttpOnly, so a page never handles it; the browser simply carries it. It names the intent it was minted by, which is what authorizes that intent's own upgrade when no Bearer is presented.", "in": "cookie", "name": "whop-core.scoped-access-token", "type": "apiKey" } } }, "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-08-25-2" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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; Account API keys return the requesting account and its connected accounts. Pass `parent_account_id` to return only that parent account's connected accounts.", "operationId": "listAccounts", "parameters": [ { "description": "The number of accounts to return (default 10, max 50).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns accounts after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of accounts to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns accounts before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort accounts by. `volume` requires `stats:read` on the parent account.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "volume" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Return only accounts with this status: `active` (includes accounts that have not entered payments review) or `suspended`.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "suspended" ], "type": "string" } }, { "description": "Free-text filter on account title or ID. `%` and `_` match literally.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Return only accounts created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Return only accounts created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Return only accounts whose lifetime USD volume is at least this value. Requires `stats:read` on the parent account.", "in": "query", "name": "volume_min", "required": false, "schema": { "type": "number" } }, { "description": "Return only accounts whose lifetime USD volume is at most this value. Requires `stats:read` on the parent account.", "in": "query", "name": "volume_max", "required": false, "schema": { "type": "number" } }, { "description": "For platforms: the parent account ID whose direct connected accounts to return. Requires `payout:account:read` on the parent account.", "in": "query", "name": "parent_account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Account" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "accounts listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "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": [] }, { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Accounts", "tags": [ "Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an account. User tokens create business accounts; Account API keys create connected accounts. Tax fields (`tax_remitted_by`, `tax_type`, `product_tax_code_id`, `business_address`, `tax_identifiers`) are configured with Update Account, not at creation.", "operationId": "createAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "affiliate_code": { "description": "The username, if any, of the partner who referred this account", "example": "random-username-45-xxxxxxxx", "type": [ "string", "null" ] }, "blueprint_id": { "description": "The blueprint App ID, prefixed `app_`. Creates a hosted website for the account and queues its deployment asynchronously; the Account response does not report deployment completion.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "country": { "description": "The ISO 3166-1 alpha-2 country code where the account's business is located (e.g. `US`). Defaults to the parent account's country for connected accounts.", "example": "US", "type": "string" }, "email": { "description": "The email address of the account owner. Required for Account API key requests.", "example": "marcus@shinetime.example", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key/value metadata to store on the account.", "example": { "external_id": "user_12345" }, "type": "object" }, "title": { "description": "The display name of the account. Defaults to `metadata.external_id` or the owner's email when omitted.", "example": "Shine Time Auto Detailing", "type": "string" } }, "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" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:create" ] }, { "bearerAuth": [ "company:create_child" ] } ], "summary": "Create Account", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/me": { "get": { "description": "Retrieves the account associated with the current 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" ], "x-whop-docs": "hidden" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/accounts/{account_id}/preferences": { "get": { "description": "Retrieves the account's preferences: a singleton settings document keyed by preference name.", "operationId": "retrieveAccountPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "ads_agreement": { "description": "The account's Whop Ads services and payment authorization agreement. While `pending_signature`, campaign launch is blocked; sign by answering `requested_information` via `PATCH /verifications/{id}`.", "properties": { "accepted_at": { "description": "When the agreement was signed, as an ISO 8601 timestamp. `null` until signed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "agreement_version": { "description": "The agreement version signed or awaiting signature, as an ISO date. `null` when no signature is required.", "example": "2026-01-01", "type": [ "string", "null" ] }, "printed_name": { "description": "The signer's printed full name. `null` until signed.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "status": { "description": "Where the account's ads services agreement stands.", "enum": [ "not_required", "pending_signature", "signed" ], "example": "signed", "type": "string" } }, "required": [ "status", "agreement_version", "printed_name", "accepted_at" ], "type": "object" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails. `null` until ads billing has been configured.", "properties": { "backup": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] }, "primary": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] } }, "required": [ "primary", "backup" ], "type": [ "object", "null" ] }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "example": "usd", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Defaults to `America/New_York` until explicitly overridden.", "example": "America/New_York", "type": "string" }, "ads_triple_whale_integration": { "description": "The account's Triple Whale integration, which pushes Whop ad spend to Triple Whale's Data-In API so it reports as a `whop` channel.", "properties": { "masked_api_key": { "description": "The leading characters of the stored Data-In API key, followed by asterisks. The full key is never returned. `null` when no key is stored.", "example": "tw_live_********", "type": [ "string", "null" ] }, "shop_domain": { "description": "The connected Shopify store domain spend is reported for, such as `acme.myshopify.com`. `null` when no store is connected.", "example": "shinetime.myshopify.com", "type": [ "string", "null" ] }, "status": { "description": "Where the integration stands. `requires_shopify_store` means no Shopify store is connected — Triple Whale keys records by Shopify shop, so no spend is reported until one is.", "enum": [ "connected", "not_connected", "requires_shopify_store" ], "example": "connected", "type": "string" } }, "required": [ "status", "masked_api_key", "shop_domain" ], "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. `false` when the account has no cards balance.", "example": false, "type": "boolean" }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "example": false, "type": "boolean" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_triple_whale_integration", "cards_auto_top_up", "dispute_fighter_enabled" ], "type": "object" } } }, "description": "preferences retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] }, { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Retrieve Account Preferences", "tags": [ "Accounts" ] }, "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the account's preferences. Each top-level key present in the body is replaced as a whole; omitted keys are left untouched. `ads_triple_whale_integration` takes the Data-In API key to connect with, or `null` to disconnect. `ads_payment_methods` always requires a `primary` entry. `backup` is optional and any pairing is allowed — two cards, `card`+`platform_balance`, or a single method — so a card-only advertiser can fund ads without a platform balance. The `primary` and `backup` must be different sources. A `platform_balance` entry may omit `id` to use the account's default Whop balance. Configuring a `card` requires a user token; account API keys can set up platform-balance billing only.", "operationId": "updateAccountPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails.", "properties": { "backup": { "description": "Optional second method charged if the primary fails. Any pairing is allowed (two cards, card+balance, balance+card); omit it to run on a single method. Must differ from the primary.", "properties": { "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`. Optional for `platform_balance` — defaults to the account's default Whop balance. Required for `card`.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" }, "type": { "description": "The funding source kind.", "enum": [ "platform_balance", "card" ], "example": "card", "type": "string" } }, "required": [ "type" ], "type": "object" }, "primary": { "properties": { "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`. Optional for `platform_balance` — defaults to the account's default Whop balance. Required for `card`.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" }, "type": { "description": "The funding source kind.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type" ], "type": "object" } }, "required": [ "primary" ], "type": "object" }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "example": "eur", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Cannot be cleared once set — pass a new value to change it.", "example": "PST8PDT", "type": "string" }, "ads_triple_whale_integration": { "description": "Connects or disconnects the Triple Whale integration. Requires a connected Shopify store, since Triple Whale keys spend records by Shopify shop.", "properties": { "api_key": { "description": "A Triple Whale Data-In API key with the `Data-In Write: Ads` scope, validated against Triple Whale before it is stored. Pass `null` to disconnect. Connecting for the first time backfills the account's existing ad spend.", "example": "tw_live_key_1234", "type": [ "string", "null" ] } }, "required": [ "api_key" ], "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. Requires a cards balance on the account.", "example": true, "type": "boolean" }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "example": true, "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "ads_agreement": { "description": "The account's Whop Ads services and payment authorization agreement. While `pending_signature`, campaign launch is blocked; sign by answering `requested_information` via `PATCH /verifications/{id}`.", "properties": { "accepted_at": { "description": "When the agreement was signed, as an ISO 8601 timestamp. `null` until signed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "agreement_version": { "description": "The agreement version signed or awaiting signature, as an ISO date. `null` when no signature is required.", "example": "2026-01-01", "type": [ "string", "null" ] }, "printed_name": { "description": "The signer's printed full name. `null` until signed.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "status": { "description": "Where the account's ads services agreement stands.", "enum": [ "not_required", "pending_signature", "signed" ], "example": "not_required", "type": "string" } }, "required": [ "status", "agreement_version", "printed_name", "accepted_at" ], "type": "object" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails. `null` until ads billing has been configured.", "properties": { "backup": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] }, "primary": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] } }, "required": [ "primary", "backup" ], "type": [ "object", "null" ] }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "example": "usd", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Defaults to `America/New_York` until explicitly overridden.", "example": "America/New_York", "type": "string" }, "ads_triple_whale_integration": { "description": "The account's Triple Whale integration, which pushes Whop ad spend to Triple Whale's Data-In API so it reports as a `whop` channel.", "properties": { "masked_api_key": { "description": "The leading characters of the stored Data-In API key, followed by asterisks. The full key is never returned. `null` when no key is stored.", "example": "tw_live_********", "type": [ "string", "null" ] }, "shop_domain": { "description": "The connected Shopify store domain spend is reported for, such as `acme.myshopify.com`. `null` when no store is connected.", "example": "shinetime.myshopify.com", "type": [ "string", "null" ] }, "status": { "description": "Where the integration stands. `requires_shopify_store` means no Shopify store is connected — Triple Whale keys records by Shopify shop, so no spend is reported until one is.", "enum": [ "connected", "not_connected", "requires_shopify_store" ], "example": "requires_shopify_store", "type": "string" } }, "required": [ "status", "masked_api_key", "shop_domain" ], "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. `false` when the account has no cards balance.", "example": false, "type": "boolean" }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "example": false, "type": "boolean" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_triple_whale_integration", "cards_auto_top_up", "dispute_fighter_enabled" ], "type": "object" } } }, "description": "preferences updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid preferences" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "forbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] }, { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Update Account Preferences", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/{account_id}/reserves": { "get": { "description": "Lists what the account's held balance is made of, one entry per currency: the total held, why each part is held, and the days it unlocks.", "operationId": "listAccountReserves", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AccountReserve" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "empty when nothing is held" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "503": { "$ref": "#/components/responses/ServiceUnavailable", "description": "reserves could not be read right now" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Account Reserves", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/{id}": { "get": { "description": "Retrieves a single account by ID or public route when it is visible to the credential, including its crypto wallet. The reserved id `me` retrieves the account associated with the current Account API key; user tokens have no single account, so they must address one by ID or route.", "operationId": "retrieveAccount", "parameters": [ { "description": "Account ID, prefixed `biz_`, its public route, or `me` for the account associated with the current API key.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account settling on stablecoin rails" }, "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" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates an account. User tokens can update business accounts; Account API keys can update connected accounts. The reserved id `me` — accepted on Retrieve Account — resolves to the requesting account, which an Account API key cannot edit, so updates must name the connected account by its `biz_` id.", "operationId": "updateAccount", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "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.", "example": true, "type": "boolean" }, "affiliate_instructions": { "description": "Guidelines shown to affiliates promoting this account.", "example": "Send us your detailing content before promoting. No paid search on our brand terms.", "type": [ "string", "null" ] }, "banner_image": { "additionalProperties": true, "description": "Account banner image, used as the cover photo when creating a Whop-managed Facebook page. Image files up to 10 MB, except `image/gif`. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file).", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "business_address": { "description": "Account business address used to calculate tax. A complete address in a supported country is required when `tax_remitted_by` is `self`.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "The legal business name used with the account's tax address.", "example": " Shine Time Auto Detailing, LLC ", "maxLength": 255, "type": [ "string", "null" ] }, "business_type": { "description": "High-level business category for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "education_program", "coaching", "software", "paid_group", "newsletter", "agency", "physical_products", "brick_and_mortar", "events", "coaching_and_courses", "other", "services", "gig_economy", "marketplace", "telehealth", "class_action_settlement", "physical_product", "saas", "course", "community", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "collect_vat_id": { "description": "Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does not require a VAT ID to purchase.", "example": true, "type": "boolean" }, "country": { "description": "Country where the account is located.", "example": "US", "type": [ "string", "null" ] }, "description": { "description": "Account promotional description. When creating a Whop-managed Facebook page, it is truncated to 155 characters and used as the About text.", "example": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "type": [ "string", "null" ] }, "featured_affiliate_product_id": { "description": "The ID of the product to feature for affiliates. Pass `null` to clear.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "home_preferences": { "description": "Public account home page preferences.", "items": { "enum": [ "hide_member_count", "hide_members_card" ], "example": "hide_member_count", "type": "string" }, "type": "array" }, "industry_group": { "description": "Account industry group. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "academic_and_test_prep", "accessories", "agriculture_and_farming", "ai_and_automation_agencies", "ai_and_automation_software", "arts_and_crafts", "automotive", "b2b_and_professional_marketplaces", "baby_and_kids", "bars_and_breweries", "beauty_and_personal_care", "beauty_and_wellness", "business_and_entrepreneurship", "business_and_money_groups", "cafes_and_quick_service", "career_and_professional", "charity_and_cause_events", "class_action_settlement", "clothing_and_apparel", "communication_and_messaging_software", "community_and_education_software", "conference_and_expo_events", "consulting", "content_and_clipping_agencies", "creative_and_content_creation", "creative_and_content_groups", "creative_and_education", "creative_gigs", "creative_services", "customer_support_agencies", "dating_and_relationships", "delivery_and_logistics", "dental_and_vision", "dermatology_and_skin", "design_and_creative_agencies", "developer_and_technical_tools", "development_agencies", "digital_and_education_marketplaces", "digital_goods_and_accounts", "e_commerce_software", "education_and_childcare", "educational_training_events", "electronics_and_gadgets", "entertainment_and_leisure", "family_and_community_events", "finance_and_investing", "fitness_and_athletics", "fitness_and_health_groups", "fitness_and_recreation", "fitness_equipment_and_gear", "food_and_beverages", "food_and_hospitality_marketplaces", "funeral_and_death_care", "gaming_and_entertainment_software", "gaming_groups", "genetic_and_specialized", "government_and_public", "health_and_wellness", "health_and_wellness_services", "healthcare", "healthcare_and_wellness_software", "hobbies_and_lifestyle", "hobby_and_interest_groups", "home_and_living", "home_and_trade_services", "home_and_trade_storefronts", "home_improvement_and_tools", "home_services_gigs", "hospitality_and_lodging", "industrial_and_manufacturing", "industry_specific_software", "language_and_communication", "legal_and_compliance", "lifestyle_and_culture", "lifestyle_and_personal_growth", "lifestyle_and_personal_growth_groups", "lifestyle_and_wellness_events", "logistics_and_transportation_services", "marketing_agencies", "marketing_and_advertising", "marketing_and_sales_software", "media_and_publishing_companies", "mental_health_and_behavioral", "miscellaneous", "music_and_performing_arts", "news_and_politics", "nonprofit_and_charity", "office_and_business_supplies", "outdoor_and_sports", "performance_and_show_events", "personal_development", "personal_finance", "personal_services", "pet_services", "pets_and_animals", "primary_and_general_care", "product_marketplaces", "productivity_and_business_ops", "professional_gigs", "professional_services", "professional_services_storefront", "publishing_and_info_products", "real_estate", "real_estate_software", "recruiting_and_staffing", "rehabilitation_and_therapy", "religion_and_faith", "rental_marketplaces", "restaurants", "retail", "sales_agencies", "sales_and_revenue", "security_and_investigations", "security_and_privacy_software", "service_marketplaces", "sleep_and_chronic_conditions", "social_and_networking_events", "social_entertainment_events", "specialized_gigs", "specialty_medical_care", "spirituality_and_mindfulness", "spirituality_and_personal_growth", "sports_and_fitness_events", "sports_betting_and_gambling", "sports_betting_groups", "supplements_and_nutrition", "sustainability_and_eco_products", "task_and_errands", "tech_and_ai", "tech_and_dev_groups", "tech_and_development", "trading_and_finance_software", "trading_and_investing", "trading_and_investing_groups", "transportation", "veterinary", "video_games_and_esports", "weight_and_metabolic_health", "wellness_and_alternative", "womens_and_mens_health", null ], "example": "automotive", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "industry_type": { "description": "Specific industry vertical for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "trading", "sports_betting", "reselling", "fitness", "amazon_fba", "real_estate", "kindle_book_publishing", "dating", "agencies", "health_and_wellness", "social_media", "sales", "business", "ecommerce", "video_games", "home_services", "ai", "public_speaking", "personal_finance", "careers", "travel", "clipping", "spirituality", "vas", "personal_development", "software", "other", "marketing_agency", "sales_agency", "ai_agency", "design_agency", "coaching_agency", "development_agency", "recruiting_agency", "customer_support_agency", "clipping_agency", "clothing", "supplements", "beauty_and_personal_care", "fitness_gear", "accessories", "home_goods", "electronics_and_gadgets", "food_and_beverages", "gym", "restaurant", "retail_store", "coffee_shop", "salon_spa", "medical_dentist_office", "hotel_lodging", "auto_repair_shop", "masterminds", "webinars", "bootcamps", "convention", "concerts", "meetups", "parties", "forex_trading", "stock_trading", "options_trading", "crypto_trading", "futures_trading", "day_trading", "swing_trading", "algorithmic_trading", "prop_firm_trading", "value_investing", "real_estate_investing", "alternative_investments", "penny_stock_trading", "dividend_investing", "index_fund_investing", "gold_precious_metals", "venture_capital_education", "private_equity_education", "technical_analysis", "forex_scalping", "ict_smc_trading", "personalized_investment_advice", "forex_signals_group", "stock_signals_group", "crypto_signals_group", "options_alerts_group", "futures_signals_group", "trading_education_group", "investing_community", "prediction_markets_group", "nft_alpha_group", "penny_stock_group", "dividend_investing_group", "real_estate_investing_group", "prop_firm_group", "forex_trading_bot", "stock_trading_platform", "crypto_trading_bot", "futures_trading_bot", "options_flow_tool", "portfolio_tracker", "financial_modeling_software", "accounting_software", "invoicing_software", "tax_software", "risk_management_software", "prop_trading_platform", "backtesting_software", "trading_indicators", "market_data_feed", "stock_research_tool", "banking_software", "lending_platform", "insurance_software", "bnpl_service", "check_cashing_service", "cloud_mining_schemes", "consumer_lending", "credit_repair_service", "crypto_exchange_brokerage", "crypto_trading_tools_software", "debt_collection_agency", "debt_relief_settlement", "escrow_service", "foreign_exchange_service", "non_custodial_wallet_tools", "payment_facilitation", "prediction_market_exchange", "stablecoin_issuance", "token_sales_ico", "tokenized_rwa", "yield_staking_products", "sports_betting_picks", "fantasy_sports", "horse_racing", "poker_coaching", "esports_betting", "sports_analytics", "nfl_betting", "nba_betting", "mlb_betting", "soccer_betting", "mma_ufc_betting", "sports_picks_group", "dfs_group", "horse_racing_group", "esports_picks_group", "nfl_picks_group", "nba_picks_group", "soccer_picks_group", "mlb_picks_group", "mma_picks_group", "prop_bets_group", "fantasy_sports_free_to_play", "licensed_gambling_operations", "unlicensed_gambling", "bodybuilding_coaching", "strength_training", "weight_loss_coaching", "athletic_performance", "yoga_instruction", "martial_arts_instruction", "running_coaching", "calisthenics", "flexibility_mobility", "nutrition_coaching", "swimming_coaching", "cycling_coaching", "boxing_coaching", "mma_coaching", "jiu_jitsu_coaching", "wrestling_coaching", "gymnastics_coaching", "pilates_instruction", "sports_nutrition", "body_recomposition", "golf_coaching", "tennis_coaching", "basketball_training", "soccer_training", "racket_sports_coaching", "fitness_accountability", "nutrition_community", "weight_loss_group", "bodybuilding_community", "running_community", "martial_arts_community", "mental_health_group", "biohacking_community", "addiction_support_group", "yoga_community", "crossfit_community", "longevity_community", "womens_fitness_community", "postpartum_fitness_group", "chronic_illness_support", "skincare_community", "mental_health_coaching", "life_coaching", "biohacking", "holistic_health", "addiction_recovery_coaching", "breathwork", "meditation_mindfulness", "gut_health_coaching", "longevity_coaching", "womens_health_coaching", "mens_health_coaching", "fertility_wellness", "stress_management", "grief_coaching", "trauma_recovery_coaching", "adhd_coaching", "biomarker_health_coaching", "telehealth_platform", "ehr_software", "practice_management", "mental_health_app", "fitness_app", "nutrition_tracking_app", "wellness_app", "patient_engagement", "medical_billing_software", "pharmacy_management", "lab_management", "clinical_trial_software", "dental_software", "veterinary_software", "health_data_platform", "fitness_newsletter", "mental_health_newsletter", "longevity_newsletter", "medical_newsletter", "biohacking_newsletter", "womens_health_newsletter", "mens_health_newsletter", "pharma_biotech_newsletter", "ecommerce_education", "amazon_fba_coaching", "dropshipping_coaching", "print_on_demand_coaching", "retail_arbitrage", "wholesale_coaching", "startup_coaching", "business_strategy", "agency_building", "smma_coaching", "consulting_business", "saas_entrepreneurship", "local_business_coaching", "cleaning_business_coaching", "trucking_business_coaching", "vending_machine_business", "atm_business_coaching", "car_wash_business", "airbnb_business_coaching", "private_label_coaching", "etsy_coaching", "merch_business_coaching", "licensing_business", "business_acquisition", "women_entrepreneurship", "affiliate_marketing_education", "coaching_business_coaching", "ecommerce_community", "agency_community", "saas_community", "saas_marketing_community", "real_estate_community", "sales_community", "affiliate_community", "reselling_community", "amazon_seller_community", "dropshipping_community", "freelancer_community", "startup_founder_community", "ceo_executive_community", "women_business_community", "marketing_community", "ai_business_community", "content_business_community", "local_business_community", "private_equity_community", "wholesaling_community", "coaching_business_community", "make_money_online_community", "startup_newsletter", "ecommerce_newsletter", "marketing_newsletter", "sales_newsletter", "small_business_newsletter", "leadership_newsletter", "agency_newsletter", "saas_newsletter", "hr_people_newsletter", "legal_business_newsletter", "real_estate_business_newsletter", "solopreneur_newsletter", "high_ticket_sales", "b2b_sales_coaching", "door_to_door_sales", "sales_funnel_coaching", "appointment_setting_coaching", "insurance_sales_coaching", "car_sales_coaching", "retail_sales_coaching", "solar_sales_coaching", "lead_generation_agency", "cold_email_agency", "cold_calling_agency", "sales_outsourcing", "crm_implementation", "appointment_setting_agency", "sales_training_agency", "revenue_operations_agency", "inbound_teleservices", "outbound_telemarketing", "facebook_ads", "google_ads", "tiktok_marketing", "youtube_marketing", "instagram_growth", "seo_coaching", "email_marketing_coaching", "copywriting_coaching", "affiliate_marketing", "local_seo", "ai_marketing", "webinar_marketing", "event_marketing", "saas_marketing_coaching", "digital_marketing", "smma", "performance_marketing_agency", "seo_agency", "content_marketing_agency", "email_marketing_agency", "influencer_marketing_agency", "pr_agency", "branding_agency", "video_marketing_agency", "amazon_marketing_agency", "podcast_marketing_agency", "tiktok_agency", "linkedin_agency", "local_marketing_agency", "dental_marketing_agency", "real_estate_marketing_agency", "restaurant_marketing_agency", "ecommerce_marketing_agency", "b2b_marketing_agency", "growth_marketing_agency", "affiliate_management_agency", "conversion_optimization_agency", "event_marketing_agency", "click_farm_service", "data_scraping_service", "lead_list_sales", "social_media_bot_farm", "crm_software", "email_marketing_software", "sms_marketing_software", "seo_tool", "landing_page_builder", "ad_management_tool", "affiliate_tracking", "review_management", "analytics_dashboard", "lead_gen_software", "link_in_bio_tool", "influencer_platform", "webinar_platform", "ab_testing_tool", "chatbot_marketing", "video_sales_tool", "proposal_software", "competitive_intelligence", "social_listening_tool", "whatsapp_marketing_tool", "standalone_tipping", "video_editing_education", "photography_coaching", "music_production", "ui_ux_design_education", "clipping_education", "ugc_creation", "3d_modeling_education", "dj_education", "youtube_automation", "blog_monetization", "wedding_photography_education", "calligraphy_lettering", "illustration_education", "fashion_design_education", "interior_design_education", "influencer_education", "ai_content_creator_education", "ai_nsfw_content_generation_education", "web_design_agency", "graphic_design_agency", "ui_ux_agency", "motion_design_agency", "product_design_agency", "logo_design_agency", "presentation_design_agency", "3d_visualization_agency", "fashion_design_agency", "video_clipping_agency", "video_production_agency", "ugc_agency", "content_writing_agency", "translation_agency", "social_media_management", "ghostwriting_agency", "podcast_editing_agency", "thumbnail_design_agency", "scriptwriting_agency", "seo_content_agency", "technical_writing_agency", "photography_service", "videography_service", "music_production_service", "voice_over_service", "event_photography", "drone_services", "commercial_photography", "portrait_photography_service", "real_estate_photography", "food_photography_service", "live_event_production", "podcast_production_service", "freelance_design_gig", "freelance_writing_gig", "freelance_dev_gig", "music_performance_gig", "event_staffing_gig", "model_talent_gig", "photography_gig", "videography_gig", "voiceover_gig", "illustration_gig", "social_media_gig", "dj_gig", "face_painting_gig", "clipping_gig", "content_creator_community", "video_editing_community", "music_producer_community", "photography_community", "writing_community", "design_community", "youtube_creator_community", "tiktok_creator_community", "podcast_community", "filmmaker_community", "clipping_community", "youtube_automation_community", "pirated_digital_content", "web_development_education", "ai_ml_education", "data_science_education", "cybersecurity_education", "cloud_computing_education", "blockchain_education", "no_code_education", "automation_education", "game_development_education", "prompt_engineering", "python_programming", "javascript_programming", "react_development", "database_engineering", "aws_certification", "data_engineering", "robotics_education", "vr_ar_development", "linux_sysadmin", "wordpress_development", "ai_agent_building", "web_development_agency", "mobile_app_agency", "saas_development_agency", "ecommerce_development", "blockchain_development_agency", "game_development_agency", "devops_agency", "ai_development_agency", "wordpress_agency", "shopify_agency", "api_integration_agency", "cybersecurity_agency", "data_engineering_agency", "vr_ar_development_agency", "hacking_tools_malware", "stalkerware_monitoring", "developer_community", "ai_community", "cybersecurity_community", "no_code_community", "indie_hacker_community", "devops_community", "data_science_community", "product_community", "open_source_community", "api_management", "hosting_platform", "database_tool", "devops_tool", "monitoring_tool", "testing_tool", "code_editor", "no_code_builder", "cdn_platform", "error_tracking", "documentation_tool", "webhook_tool", "3d_weapon_files", "background_check_services", "document_falsification", "fake_id_services", "fake_reference_services", "real_estate_wholesaling", "house_flipping", "property_development", "rental_property", "airbnb_str", "commercial_real_estate", "land_investing", "section_8_housing", "mobile_home_investing", "multifamily_investing", "self_storage_investing", "property_management_education", "vacation_rental_management", "real_estate_crm", "property_management_software", "deal_analysis_tool", "mls_search_tool", "virtual_tour_software", "real_estate_marketing_software", "construction_management", "home_valuation_tool", "credit_repair_education", "budgeting_coaching", "tax_strategy_education", "wealth_building", "student_loan_strategy", "credit_card_optimization", "career_coaching", "executive_coaching", "management_coaching", "tech_career_coaching", "medical_career_coaching", "trade_skills_education", "va_training", "bookkeeping_education", "data_career_coaching", "cybersecurity_career", "consulting_career", "investment_banking_career", "law_career_coaching", "nursing_career_coaching", "teaching_career_coaching", "personal_branding_career", "mens_dating_coaching", "womens_dating_coaching", "relationship_coaching", "marriage_coaching", "communication_coaching", "masculinity_coaching", "femininity_coaching", "breakup_recovery", "manifestation_coaching", "astrology_coaching", "energy_healing", "spiritual_coaching", "faith_based_coaching", "psychic_development", "numerology_coaching", "chakra_healing", "shamanic_healing", "biblical_coaching", "islamic_coaching", "productivity_coaching", "public_speaking_coaching", "mindset_coaching", "stoicism_philosophy", "mens_self_improvement", "womens_self_improvement", "leadership_development", "anger_management", "neurolinguistic_programming", "appearance_and_grooming_coaching", "amazon_kdp", "self_publishing", "audiobook_publishing", "course_creation", "digital_product_creation", "ghostwriting_business", "template_creation", "ai_book_publishing", "language_learning", "tutoring", "college_admissions_coaching", "cpa_exam_prep", "bar_exam_prep", "real_estate_exam_prep", "medical_board_prep", "pmp_certification_prep", "aws_certification_prep", "comptia_certification", "ap_exam_prep", "graduate_school_prep", "scholarship_coaching", "homeschool_education", "stem_education", "financial_certification", "coding_bootcamp_prep", "cooking_culinary", "travel_coaching", "parenting_coaching", "pet_training", "gardening_education", "diy_crafts", "survival_prepping", "baking_pastry", "wine_sommelier", "beer_brewing", "mixology_bartending", "woodworking", "pottery_ceramics", "knitting_crocheting", "jewelry_making", "aquarium_fishkeeping", "bird_watching", "astronomy_education", "magic_illusion", "car_restoration", "motorcycle_riding", "sailing_boating", "scuba_diving", "rock_climbing", "skiing_snowboarding", "surfing_education", "homesteading", "tiny_house_living", "van_life", "fashion_styling", "floral_design", "travel_planning_service", "collectibles_coaching", "car_enthusiast_community", "sneakerhead_community", "watch_collector_community", "wine_enthusiast_community", "cigar_community", "cooking_community", "gardening_community", "fishing_community", "hunting_community", "diy_maker_community", "golf_community", "collectibles_community", "sweepstakes_raffles", "event_ticket_community", "esports_coaching", "game_specific_coaching", "gaming_community", "game_account_selling", "unauthorized_ingame_currency", "legal_education", "music_theory", "music_business", "acting_coaching", "dance_instruction", "voice_acting", "english_coaching", "spanish_coaching", "mandarin_coaching", "french_coaching", "german_coaching", "japanese_coaching", "korean_coaching", "arabic_coaching", "sign_language_education", "accent_reduction", "business_english", "ai_chatbot_agency", "ai_automation_agency", "ai_consulting", "workflow_automation_agency", "data_analytics_agency", "ai_voice_agent_agency", "ai_content_agency", "machine_learning_agency", "computer_vision_agency", "tech_recruiting_agency", "executive_recruiting", "staffing_agency", "remote_staffing", "healthcare_recruiting", "va_placement_agency", "sales_recruiting", "creative_recruiting", "finance_recruiting", "legal_recruiting", "construction_staffing", "hospitality_staffing", "customer_support_outsourcing", "live_chat_agency", "technical_support_agency", "call_center_agency", "multilingual_support_agency", "community_management_agency", "management_consulting", "financial_consulting", "hr_consulting", "operations_consulting", "it_consulting", "sustainability_consulting", "legal_consulting", "compliance_consulting", "supply_chain_consulting", "change_management_consulting", "digital_transformation_consulting", "healthcare_consulting", "real_estate_consulting", "franchise_consulting", "export_trade_consulting", "nonprofit_consulting", "education_consulting", "cannabis_consulting", "restaurant_consulting", "m_and_a_consulting", "pricing_strategy_consulting", "brand_strategy_consulting", "saas_marketing_consulting", "done_for_you_services", "prop_firm_passing_service", "trading_account_management", "done_for_you_trading", "accounting_bookkeeping", "tax_preparation", "legal_services", "notary_services", "insurance_brokerage", "financial_planning_service", "real_estate_services", "property_management", "mortgage_brokerage", "immigration_services", "patent_trademark_services", "business_formation_services", "shell_company_formation", "payroll_services", "audit_services", "forensic_accounting", "actuarial_services", "appraisal_services", "mediation_arbitration", "bail_bond_services", "crowdfunding_platform", "essay_mill_paper_mill", "government_service_facilitation", "immigration_services_unlicensed", "licensed_legal_services", "personalized_tax_services", "private_investigation", "repossession_services", "unlicensed_legal_services", "record_label", "book_publishing_house", "news_media_outlet", "radio_broadcasting", "tv_production_company", "film_studio", "magazine_publisher", "music_licensing_agency", "talent_management_agency", "advertising_network", "ad_tech_platform", "cleaning_service", "landscaping_service", "plumbing_service", "electrical_service", "hvac_service", "roofing_service", "painting_service", "moving_service", "handyman_service", "pest_control", "pool_service", "solar_installation", "home_renovation", "pressure_washing", "junk_removal", "garage_door_service", "fencing_service", "concrete_masonry", "tree_service", "window_cleaning", "gutter_service", "flooring_service", "cabinet_countertop", "home_inspection", "septic_service", "waterproofing_service", "insulation_service", "chimney_service", "locksmith_service", "glass_window_service", "epoxy_coating", "private_security_guard_service", "armored_car_transport", "executive_protection_bodyguard", "event_security_service", "alarm_system_installation", "cctv_installation", "private_investigation_agency", "background_check_provider", "locksmith_commercial", "bounty_hunter_bail_enforcement", "personal_styling", "personal_chef", "personal_assistant_service", "tutoring_service", "pet_services", "wedding_planning", "concierge_service", "personal_training_service", "nanny_service", "elder_care_service", "errand_service", "life_organization", "relocation_service", "adult_dating_services", "escort_services", "hotel_accommodation_bookings", "mail_order_spouse", "psychic_fortune_telling", "timeshare_sales", "freight_brokerage", "courier_service", "warehousing_service", "last_mile_delivery", "auto_transport", "international_shipping", "cold_chain_logistics", "commercial_airline_tickets", "cruise_line_bookings", "contract_manufacturing", "cnc_machining_service", "3d_printing_service_commercial", "plastic_injection_molding", "metal_fabrication", "pcba_assembly", "chemical_manufacturing", "textile_manufacturing", "food_processing_facility", "packaging_manufacturing", "industrial_automation_integrator", "mining_and_extraction", "oil_and_gas_services", "renewable_energy_generation", "waste_management_recycling", "hazardous_waste_disposal", "aerospace_defense_contracting", "personal_training_studio", "nutrition_consulting", "mental_health_counseling", "physical_therapy_service", "occupational_therapy_service", "speech_therapy_service", "chiropractic_service", "acupuncture_service", "massage_therapy_service", "midwifery_doula", "lactation_consulting", "dietitian_service", "addiction_recovery_services", "dtc_lab_testing", "iv_therapy_infusion", "medspa_aesthetic_services", "prescription_delivery_services", "registered_dietitian_services", "unlicensed_therapy_counseling", "streetwear", "athleisure", "luxury_fashion", "kids_clothing", "custom_apparel", "workwear", "swimwear", "lingerie_intimates", "vintage_clothing", "plus_size_fashion", "maternity_clothing", "sleepwear_loungewear", "denim_brand", "outerwear_jackets", "socks_hosiery", "costumes_cosplay", "scrubs_medical_apparel", "dance_performance_wear", "hunting_camo_apparel", "casual_everyday_clothing", "protein_supplements", "vitamins_minerals", "pre_workout", "nootropics", "herbal_supplements", "weight_management_supplements", "gut_health", "cbd_products", "mushroom_supplements", "collagen_supplements", "testosterone_boosters", "sleep_supplements", "immune_support", "joint_bone_health", "greens_powder", "creatine_supplements", "electrolyte_hydration", "prenatal_supplements", "kids_supplements", "pet_supplements", "ayurvedic_supplements", "keto_supplements", "cannabis_thc_products", "cbd_hemp_products_compliant", "delta8_thc_products", "dietary_supplements", "drug_precursor_chemicals", "illegal_drugs", "kratom_kava_products", "medical_treatment_claims_product", "nutraceutical_products", "otc_medication_sales", "performance_enhancing_drugs", "research_chemicals_dangerous", "research_peptides", "sexual_enhancement_products", "tobacco_products", "unlicensed_rx_sales", "skincare", "haircare", "cosmetics_makeup", "mens_grooming", "fragrance", "oral_care", "sunscreen_spf", "hair_growth_products", "body_care", "deodorant", "lip_care", "acne_treatment", "men_skincare", "baby_skincare", "tattoo_aftercare", "intimate_care", "home_gym_equipment", "yoga_equipment", "combat_sports_gear", "outdoor_fitness_gear", "wearable_fitness", "recovery_equipment", "weightlifting_equipment", "cardio_equipment", "gymnastics_equipment", "swimming_gear", "jump_rope_equipment", "grip_strength_tools", "sauna_cold_plunge", "posture_correctors", "jewelry", "sunglasses_eyewear", "bags_wallets", "hats_headwear", "phone_accessories", "travel_accessories", "scarves_wraps", "belts", "hair_accessories", "tech_accessories", "keychains_charms", "custom_engraved_accessories", "cannabis_accessories_non_drug", "drug_paraphernalia", "high_value_goods_over_500", "precious_metals_stones", "replica_counterfeit_goods", "home_decor", "candles_scents", "kitchenware", "bedding_linens", "smart_home", "cleaning_products", "outdoor_furniture", "organization_storage", "wall_art_prints", "rugs_carpets", "lighting_fixtures", "planters_garden_decor", "bathroom_accessories", "luxury_home_goods", "seasonal_holiday_decor", "pet_home_products", "home_fragrance_diffusers", "hazardous_chemicals_b2c", "pre_orders_delayed_delivery", "audio_equipment", "camera_equipment", "gaming_hardware", "drones_robotics", "ev_accessories", "charging_power", "smart_wearables", "home_security_devices", "3d_printers", "projectors_displays", "streaming_devices", "vr_headsets", "e_readers", "portable_tech", "hardware_wallets", "regulated_medical_devices", "signal_jamming_devices", "spy_cameras_hidden_recording", "specialty_coffee_tea", "health_food", "snacks_treats", "sauces_condiments", "alcohol_spirits", "meal_kits", "baked_goods", "beverages", "pet_food_treats", "protein_bars_snacks", "jerky_meat_snacks", "chocolate_confections", "honey_sweeteners", "olive_oil_vinegar", "hot_sauce", "dried_fruit_nuts", "baby_food", "plant_based_food", "gluten_free_food", "keto_food_products", "subscription_food_box", "kombucha_fermented", "alcohol_sales", "baby_products", "kids_toys", "kids_educational", "baby_clothing_accessories", "nursery_decor", "kids_outdoor_play", "kids_books", "baby_safety_products", "kids_arts_crafts", "camping_hiking", "fishing_gear", "hunting_gear", "cycling_gear", "water_sports_gear", "golf_equipment", "snow_sports_gear", "climbing_gear", "archery_equipment", "skateboarding_gear", "pickleball_equipment", "tennis_equipment", "equestrian_gear", "tactical_gear", "overlanding_gear", "explosives_fireworks", "firearms_sales", "self_defense_products", "weapon_components", "craft_kits", "sewing_textiles", "stationery", "scrapbooking_supplies", "beading_jewelry_supplies", "pottery_supplies", "printmaking_supplies", "car_accessories", "detailing_products", "motorcycle_gear", "truck_accessories", "off_road_parts", "car_audio_electronics", "performance_parts", "car_care_products", "ev_charging_accessories", "auto_repair_service", "auto_body_shop", "car_dealership", "car_wash", "tire_shop", "oil_change_shop", "auto_parts_store", "motorcycle_shop", "ev_charging_station", "transmission_shop", "muffler_exhaust_shop", "auto_glass_shop", "auto_upholstery_shop", "car_audio_shop", "smog_emissions_shop", "truck_repair_shop", "rv_repair_shop", "boat_repair_shop", "used_car_lot", "auto_auction", "dog_products", "cat_products", "aquarium_supplies", "bird_supplies", "reptile_supplies", "horse_supplies", "pet_apparel", "pet_tech", "pet_grooming_products", "hand_tools", "power_tools_and_accessories", "hardware_and_fasteners", "workshop_equipment_and_storage", "safety_and_work_gear", "painting_and_building_supplies", "office_supplies", "desk_accessories", "printing_supplies", "shipping_packaging", "reusable_products", "solar_powered_products", "christian_books_bibles", "christian_apparel", "christian_jewelry", "christian_home_decor", "jewish_judaica", "jewish_books_torah", "jewish_apparel", "islamic_books_quran", "islamic_apparel", "islamic_prayer_goods", "hindu_puja_supplies", "hindu_books_texts", "buddhist_meditation_goods", "buddhist_books_texts", "sikh_religious_goods", "other_religious_products", "handmade_goods_marketplace", "vintage_resale_marketplace", "electronics_marketplace", "auto_parts_marketplace", "luxury_goods_marketplace", "collectibles_marketplace", "wholesale_marketplace", "local_goods_marketplace", "sneaker_marketplace", "book_marketplace", "furniture_marketplace", "musical_instrument_marketplace", "art_marketplace", "ticket_marketplace", "industrial_equipment_marketplace", "craft_supply_marketplace", "baby_kids_marketplace", "outdoor_gear_marketplace", "pet_marketplace", "sustainable_goods_marketplace", "cultural_artifacts_looted", "dropshipping_operations", "endangered_animal_products", "human_body_parts_tissue", "nft_marketplace", "penny_auction", "primary_event_ticketing", "freelancer_marketplace", "home_services_marketplace", "tutoring_marketplace", "legal_services_marketplace", "healthcare_marketplace", "wedding_services_marketplace", "creative_and_content_creation_marketplace", "beauty_services_marketplace", "fitness_trainer_marketplace", "pet_services_marketplace", "childcare_marketplace", "elder_care_marketplace", "translation_marketplace", "coaching_marketplace", "therapy_marketplace", "photography_marketplace", "dj_entertainment_marketplace", "auto_services_marketplace", "freelance_marketplace_operator", "equipment_rental_marketplace", "vehicle_rental_marketplace", "space_rental_marketplace", "vacation_rental_marketplace", "clothing_rental_marketplace", "camera_gear_rental", "rv_camper_rental", "boat_rental_marketplace", "storage_rental_marketplace", "office_coworking_rental", "parking_rental_marketplace", "restaurant_marketplace", "grocery_marketplace", "catering_marketplace", "homemade_food_marketplace", "meal_prep_marketplace", "bakery_marketplace", "farm_produce_marketplace", "chef_booking_marketplace", "course_marketplace", "template_marketplace", "stock_media_marketplace", "music_beats_marketplace", "ebook_marketplace", "plugin_theme_marketplace", "3d_model_marketplace", "prompt_marketplace", "code_snippet_marketplace", "affiliate_marketing_platform", "game_cheats_hacks", "weapon_blueprint_distribution", "saas_marketplace", "agency_marketplace", "manufacturing_marketplace", "logistics_marketplace", "commercial_real_estate_marketplace", "business_for_sale_marketplace", "food_delivery", "grocery_delivery", "package_delivery", "moving_labor", "alcohol_delivery", "pharmacy_delivery", "flower_delivery_gig", "furniture_delivery_gig", "catering_delivery", "rideshare", "chauffeur_service", "bike_scooter_rental", "boat_charter_gig", "moving_truck_rental_gig", "assembly_installation", "waiting_line_service", "personal_shopping", "grocery_shopping_gig", "gift_wrapping_gig", "notary_gig", "laundry_gig", "car_wash_gig", "cleaning_gig", "lawn_care_gig", "handyman_gig", "pet_care_gig", "childcare_gig", "elder_care_gig", "painting_gig", "snow_removal_gig", "pool_cleaning_gig", "organizing_gig", "pressure_washing_gig", "junk_removal_gig", "consulting_gig", "accounting_gig", "legal_gig", "healthcare_gig", "teaching_gig", "translation_gig", "data_entry_gig", "research_gig", "virtual_assistant_gig", "sales_gig", "recruiting_gig", "mystery_shopping", "focus_group_gig", "product_testing_gig", "drone_pilot_gig", "fitness_instruction_gig", "tour_guide_gig", "dating_community", "personal_development_community", "spirituality_community", "parenting_community", "travel_community", "networking_community", "faith_community", "mens_community", "womens_community", "expat_community", "adult_community_nsfw", "hate_violence_communities", "personal_fundraising", "political_fundraising", "political_organizations", "pornographic_content", "registered_501c3", "religious_organization", "unregistered_charities", "ai_outreach_tool", "ai_chatbot_software", "ai_writing_tool", "ai_image_generator", "ai_video_tool", "ai_voice_tool", "ai_data_analysis", "ai_code_assistant", "ai_meeting_assistant", "workflow_automation_software", "ai_sales_tool", "ai_customer_support", "ai_recruiting_tool", "ai_translation_tool", "ai_music_tool", "ai_presentation_tool", "ai_research_tool", "ai_seo_tool", "ai_social_media_tool", "ai_phone_agent", "ai_legal_tool", "ai_healthcare_tool", "llm_api_platform", "ai_agent_platform", "generative_ai_platform", "celebrity_impersonation", "deepfake_service", "ai_nsfw_content_generator", "ecommerce_platform", "product_research_tool", "price_tracker", "shipping_software", "print_on_demand_software", "marketplace_seller_tool", "resale_arbitrage_tool", "reseller_management_tool", "product_review_software", "returns_management", "product_feed_management", "checkout_optimization", "wholesale_ordering", "project_management_software", "team_communication", "video_conferencing", "document_collaboration", "time_tracking_software", "scheduling_software", "hr_software", "knowledge_base_software", "form_survey_builder", "note_taking_app", "task_management", "contract_management", "expense_management", "okr_goal_tracking", "employee_engagement", "onboarding_software", "applicant_tracking", "asset_management", "facility_management", "visitor_management", "community_platform", "event_management_software", "webinar_software", "school_management", "newsletter_platform", "podcast_hosting", "forum_software", "virtual_classroom", "restaurant_pos", "salon_software", "gym_management_software", "auto_shop_software", "legal_practice_software", "church_management", "nonprofit_software", "logistics_software", "agriculture_software", "field_service_software", "marina_management", "hotel_pms", "childcare_management", "cleaning_business_software", "roofing_software", "landscaping_software", "pest_control_software", "tattoo_studio_software", "cannabis_software", "password_manager", "cybersecurity_software", "identity_verification", "backup_recovery", "endpoint_protection", "email_security", "access_management", "compliance_software", "data_privacy_tool", "vpn_services", "people_search_tool", "game_mod_tool", "streaming_tool", "game_server_hosting", "music_software", "video_editing_software", "photo_editing_software", "animation_software", "audio_editing_software", "screen_recording_software", "sports_betting_tool", "fantasy_sports_paid_entry", "iptv_pirated_streaming", "loot_boxes_gacha", "skill_contests_free_entry", "skill_contests_paid_entry", "only_fans_management_software", "pornography_platform", "business_phone_system", "customer_messaging", "digital_key_reselling", "streaming_account_reselling", "subscription_account_sharing", "account_generation_tool", "primary_care_telehealth", "urgent_care_telehealth", "pediatric_telehealth", "geriatric_telehealth", "family_medicine_telehealth", "internal_medicine_telehealth", "preventive_care_telehealth", "licensed_online_pharmacy", "telemedicine_practitioner_services", "dermatology_telehealth", "acne_telehealth", "psoriasis_eczema_telehealth", "skin_cancer_screening_tele", "cosmetic_dermatology_tele", "therapy_telehealth", "psychiatry_telehealth", "addiction_telehealth", "couples_therapy_telehealth", "child_psychology_telehealth", "eating_disorder_telehealth", "ptsd_trauma_telehealth", "adhd_telehealth", "anxiety_depression_telehealth", "ocd_telehealth", "grief_counseling_telehealth", "anger_management_telehealth", "family_therapy_telehealth", "group_therapy_telehealth", "licensed_psychedelic_therapy", "womens_health_telehealth", "mens_health_telehealth", "sexual_health_telehealth", "fertility_telehealth", "hormone_therapy_telehealth", "menopause_telehealth", "prenatal_telehealth", "postpartum_telehealth", "erectile_dysfunction_tele", "hair_loss_telehealth", "birth_control_telehealth", "sti_testing_telehealth", "dental_telehealth", "orthodontics_telehealth", "optometry_telehealth", "oral_surgery_consultation", "vision_therapy_telehealth", "cardiology_telehealth", "endocrinology_telehealth", "neurology_telehealth", "orthopedic_telehealth", "allergy_telehealth", "ent_telehealth", "rheumatology_telehealth", "gastroenterology_telehealth", "infectious_disease_telehealth", "pulmonology_telehealth", "nephrology_telehealth", "oncology_telehealth", "hematology_telehealth", "urology_telehealth", "weight_management_telehealth", "glp1_weight_loss_tele", "diabetes_management_tele", "metabolic_health_tele", "bariatric_telehealth", "physical_therapy_telehealth", "occupational_therapy_tele", "speech_therapy_telehealth", "pain_management_telehealth", "cardiac_rehab_telehealth", "pelvic_floor_telehealth", "vestibular_telehealth", "sleep_medicine_telehealth", "chronic_disease_management", "chronic_pain_telehealth", "migraine_telehealth", "asthma_copd_telehealth", "nutrition_telehealth", "naturopathic_telehealth", "functional_medicine_telehealth", "acupuncture_telehealth", "health_coaching_telehealth", "integrative_medicine_tele", "ayurvedic_telehealth", "genetic_counseling_telehealth", "pharmacogenomics_tele", "rare_disease_telehealth", "second_opinion_telehealth", "vet_telehealth", "pet_behavior_telehealth", "exotic_pet_telehealth", "equine_telehealth", "veterinary_services", "class_action_settlement", "mastermind_event", "webinar_event", "virtual_summit", "bootcamp_event", "workshop_seminar", "hackathon", "corporate_training_event", "training_certification_event", "convention_expo", "conference_summit", "industry_awards_event", "product_launch_event", "investor_demo_day", "panel_discussion_event", "pitch_competition", "meetup_event", "dinner_event", "alumni_event", "community_gathering", "singles_event", "professional_happy_hour", "women_networking_event", "founders_dinner", "industry_mixer", "concert_event", "comedy_show", "theater_performance", "film_screening", "music_festival", "cultural_festival", "fashion_show", "drag_show", "magic_show", "dance_performance", "poetry_spoken_word", "art_exhibition", "party_event", "trivia_night", "wine_tasting_event", "beer_festival", "car_show", "food_festival", "fitness_challenge_event", "marathon_race", "tournament_event", "fight_event", "yoga_retreat_event", "outdoor_adventure_event", "esports_tournament", "obstacle_course_race", "cycling_event", "swim_meet", "golf_tournament", "pickleball_tournament", "crossfit_competition", "martial_arts_tournament", "surfing_competition", "wellness_retreat", "spiritual_retreat", "couples_retreat", "plant_medicine_retreat", "luxury_experience_event", "detox_retreat", "silent_retreat", "creative_retreat", "leadership_retreat", "mens_retreat", "womens_retreat", "digital_detox_retreat", "fundraiser_event", "awareness_event", "volunteer_event", "charity_auction", "benefit_concert", "charity_run_walk", "environmental_cleanup", "family_festival", "kids_event", "holiday_event", "farmers_market_event", "block_party", "graduation_ceremony", "memorial_event", "stock_market_newsletter", "crypto_newsletter", "personal_finance_newsletter", "real_estate_newsletter", "fintech_newsletter", "venture_capital_newsletter", "options_trading_newsletter", "forex_newsletter", "macro_economics_newsletter", "alternative_investing_newsletter", "tax_strategy_newsletter", "ai_newsletter", "tech_industry_newsletter", "cybersecurity_newsletter", "developer_newsletter", "product_newsletter", "devops_newsletter", "open_source_newsletter", "robotics_newsletter", "climate_tech_newsletter", "travel_newsletter", "fashion_newsletter", "parenting_newsletter", "sports_newsletter", "gaming_newsletter", "music_entertainment_newsletter", "book_reading_newsletter", "dating_relationships_newsletter", "home_design_newsletter", "pet_newsletter", "wine_spirits_newsletter", "automotive_newsletter", "political_newsletter", "geopolitics_newsletter", "media_journalism_newsletter", "defense_security_newsletter", "legal_policy_newsletter", "design_newsletter", "education_newsletter", "science_newsletter", "philosophy_newsletter", "sustainability_newsletter", "architecture_newsletter", "history_newsletter", "psychology_newsletter", "career_newsletter", "spirituality_newsletter", "self_improvement_newsletter", "productivity_newsletter", "faith_newsletter", "gym_facility", "crossfit_box", "yoga_studio", "pilates_studio", "martial_arts_gym", "boxing_gym", "climbing_gym", "dance_studio", "swimming_pool", "sports_facility", "golf_course", "bowling_alley", "skating_rink", "trampoline_park", "tennis_club", "pickleball_facility", "gymnastics_center", "spin_studio", "barre_studio", "personal_training_studio_bm", "recovery_studio", "indoor_soccer", "batting_cage", "shooting_range", "archery_range", "equestrian_center", "fine_dining", "fast_casual_restaurant", "steakhouse", "seafood_restaurant", "pizza_shop", "sushi_restaurant", "deli_sandwich_shop", "bbq_restaurant", "mexican_restaurant", "italian_restaurant", "chinese_restaurant", "indian_restaurant", "thai_restaurant", "korean_restaurant", "mediterranean_restaurant", "vegan_vegetarian_restaurant", "brunch_restaurant", "ramen_noodle_shop", "poke_bowl_shop", "ethnic_restaurant", "coffee_shop_cafe", "bakery", "juice_smoothie_bar", "ice_cream_shop", "donut_shop", "bubble_tea_shop", "food_truck", "fast_food", "ghost_kitchen", "food_hall_vendor", "catering_kitchen", "butcher_shop", "cheese_shop", "farmers_market_stall", "bar_lounge", "brewery_taproom", "winery_tasting", "wine_bar", "cocktail_bar", "sports_bar", "hookah_lounge", "distillery", "commercial_farming", "livestock_ranching", "hydroponic_vertical_farming", "forestry_logging", "aquaculture_fisheries", "vineyard_winery_production", "cannabis_cultivation", "hemp_farming", "grain_production", "agricultural_cooperative", "fertilizer_pesticide_sales", "farm_equipment_sales", "boutique_store", "clothing_store", "shoe_store", "jewelry_store", "electronics_store", "bookstore", "pet_store", "toy_store", "sporting_goods_store", "thrift_store", "smoke_shop", "cannabis_dispensary", "convenience_store", "grocery_store", "liquor_store", "florist", "gift_shop", "furniture_store", "home_improvement_store", "art_gallery_retail", "music_instrument_store", "outdoor_recreation_store", "phone_repair_store", "watch_store", "bridal_shop", "maternity_store", "kids_store", "sneaker_store", "vintage_store", "comic_book_store", "record_store", "craft_supply_store", "fabric_store", "health_food_store", "vitamin_supplement_store", "optical_store", "mattress_store", "appliance_store", "kitchen_bath_store", "tile_flooring_store", "paint_store", "garden_center", "gun_store", "pawn_shop", "dollar_store", "hair_salon", "nail_salon", "day_spa", "med_spa", "massage_studio", "tattoo_parlor", "tanning_salon", "beauty_supply_store", "lash_brow_studio", "waxing_studio", "sauna_bathhouse", "cryotherapy_studio", "float_sensory_studio", "iv_therapy_lounge", "teeth_whitening_studio", "microblading_studio", "spray_tan_studio", "blowout_bar", "mens_barbershop", "kids_salon", "medical_office", "dental_office", "chiropractic_office", "physical_therapy_clinic", "optometry_office", "dermatology_clinic", "urgent_care_clinic", "pharmacy", "veterinary_clinic", "mental_health_clinic", "fertility_clinic", "acupuncture_clinic", "hearing_aid_center", "orthopedic_clinic", "pediatric_clinic", "cosmetic_surgery_center", "allergy_clinic", "pain_management_clinic", "dialysis_center", "imaging_center", "lab_testing_center", "sleep_clinic", "weight_loss_clinic", "hormone_therapy_clinic", "addiction_treatment_center", "rehabilitation_center", "occupational_therapy_clinic", "speech_therapy_clinic", "wound_care_center", "funeral_home_mortuary", "crematory_service", "cemetery_memorial_park", "casket_urn_retailer", "pet_cremation_service", "biohazard_cleanup", "estate_liquidation", "hotel", "motel", "boutique_hotel", "bed_and_breakfast", "hostel", "resort", "campground_rv", "vacation_rental_property", "extended_stay", "glamping_site", "cabin_rental", "eco_lodge", "retreat_center", "tutoring_center", "daycare_center", "preschool", "learning_center", "music_school", "art_school", "driving_school", "language_school", "trade_school", "coding_bootcamp_location", "montessori_school", "after_school_program", "swim_school", "cooking_school", "test_prep_center", "special_needs_center", "adult_education_center", "flight_school", "cosmetology_school", "movie_theater", "escape_room", "arcade", "mini_golf", "laser_tag", "go_kart", "amusement_park", "museum", "zoo_aquarium", "theater_venue", "nightclub", "karaoke_bar", "comedy_club", "live_music_venue", "axe_throwing", "virtual_reality_arcade", "board_game_cafe", "cat_cafe", "haunted_house", "water_park", "indoor_playground", "concert_venue", "drive_in_theater", "billiards_hall", "dart_bar", "indoor_skydiving", "law_office", "real_estate_office", "insurance_office", "accounting_office", "bank_credit_union", "printing_shop", "shipping_center", "dry_cleaner", "laundromat", "storage_facility", "coworking_space", "check_cashing", "title_company", "travel_agency_storefront", "staffing_office", "financial_advisor_office", "immigration_office", "bail_bonds_office", "pet_grooming", "dog_daycare", "pet_boarding", "dog_training_facility", "pet_spa", "aquatic_pet_store", "pet_bakery", "pet_photography_studio", "plumbing_showroom", "hvac_showroom", "solar_showroom", "kitchen_design_showroom", "bath_design_showroom", "window_door_showroom", "pool_spa_showroom", "fireplace_showroom", "countertop_showroom", "nonprofit_organization", "charity_foundation", "political_campaign", "community_organization", "environmental_nonprofit", "education_nonprofit", "health_nonprofit", "animal_welfare_nonprofit", "arts_culture_nonprofit", "social_justice_nonprofit", "veterans_nonprofit", "youth_nonprofit", "disaster_relief_nonprofit", "food_bank", "housing_nonprofit", "government_agency", "public_utility", "public_library", "public_school", "municipal_service", "military_installation", "embassy_consulate", "niche_service", "niche_product", "hybrid_business", "other_general", "holding_company", "family_office", "cooperative", "social_enterprise", "incubator_accelerator", "coworking_community", "media_company", "research_lab", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "invoice_prefix": { "description": "Prefix used for account invoices.", "example": "SHINE", "type": [ "string", "null" ] }, "logo": { "additionalProperties": true, "description": "Account logo, used as the profile picture when creating a Whop-managed Facebook page. Image files up to 5 MB. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file).", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Arbitrary key/value metadata to store on the account.", "example": { "external_id": "shop_4417", "region": "austin" }, "type": "object" }, "onboarding_type": { "description": "The type of onboarding the account has completed.", "enum": [ "platform", "seller", null ], "example": "seller", "type": [ "string", "null" ] }, "opengraph_image": { "additionalProperties": true, "description": "Open Graph preview media used when the account is shared. Image and video files up to 5 MB. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file).", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "opengraph_image_variant": { "description": "The account Open Graph image variant.", "enum": [ "white", "black", "orange", null ], "example": "black", "type": [ "string", "null" ] }, "other_business_description": { "description": "The description of the business type when business_type is other.", "example": "Mobile auto detailing", "type": [ "string", "null" ] }, "other_industry_description": { "description": "The description of the industry type when industry_type is other.", "example": "Automotive services", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "ID of the tax classification code applied by default to the account's products. See the available [product categories](https://docs.numeral.com/essentials/product-categories).", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "require_2fa": { "description": "Whether the account requires authorized users to have two-factor authentication enabled.", "example": true, "type": "boolean" }, "route": { "description": "The unique URL slug for the account.", "example": "shine-time-detailing", "type": [ "string", "null" ] }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this account.", "example": false, "type": "boolean" }, "show_joined_whops": { "description": "Whether the account appears in joined whops on other accounts.", "example": false, "type": "boolean" }, "show_reviews_dtc": { "description": "Whether reviews are displayed on direct-to-consumer product pages.", "example": false, "type": "boolean" }, "show_user_directory": { "description": "Whether the account shows users in the user directory.", "example": false, "type": "boolean" }, "social_links": { "description": "The full list of social links to display for the account.", "items": { "additionalProperties": true, "example": { "url": "https://instagram.com/shinetimedetail", "website": "instagram" }, "type": "object" }, "type": "array" }, "store_page_config": { "description": "Account store page display configuration.", "properties": { "accent_color": { "description": "Accent color used on the account store page.", "enum": [ "ruby", "tomato", "red", "crimson", "pink", "plum", "purple", "violet", "iris", "cyan", "teal", "jade", "green", "grass", "brown", "blue", "orange", "indigo", "sky", "mint", "yellow", "amber", "lime", "lemon", "magenta", "gold", "bronze", "gray", null ], "example": "red", "type": [ "string", "null" ] }, "layout": { "description": "Layout used on the account store page.", "enum": [ "featured", "compact", null ], "example": "compact", "type": [ "string", "null" ] }, "profile_variant": { "description": "Profile presentation used on the account store page.", "enum": [ "personal", "business", null ], "example": "business", "type": [ "string", "null" ] }, "whop_affiliate_link": { "description": "Whether the account store page shows a Whop affiliate link.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "target_audience": { "description": "The target audience for this account.", "example": "Owners of new and enthusiast vehicles in Austin, TX", "type": [ "string", "null" ] }, "tax_collection_enabled_states": { "description": "US state codes (50 states plus `DC`) where the account collects tax. Replaces the full set on update. Only settable when `tax_remitted_by` is `self`.", "items": { "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "example": "TX", "type": "string" }, "type": "array" }, "tax_identifiers": { "description": "Account tax/VAT registrations to add or update. When `tax_remitted_by` is `self`, tax is calculated and collected only in the countries where the account holds a registration.", "items": { "properties": { "tax_id_type": { "description": "Tax ID type, for example `eu_vat`, `gb_vat`, or `us_ein`.", "enum": [ "ad_nrt", "ao_tin", "ar_cuit", "al_tin", "am_tin", "aw_tin", "au_abn", "au_arn", "eu_vat", "az_tin", "bs_tin", "bh_vat", "bd_bin", "bb_tin", "by_tin", "bj_ifu", "bo_tin", "ba_tin", "br_cnpj", "br_cpf", "bg_uic", "bf_ifu", "kh_tin", "cm_niu", "ca_bn", "ca_gst_hst", "ca_pst_bc", "ca_pst_mb", "ca_pst_sk", "ca_qst", "cv_nif", "cl_tin", "cn_tin", "co_nit", "cd_nif", "cr_tin", "hr_oib", "do_rcn", "ec_ruc", "eg_tin", "sv_nit", "et_tin", "eu_oss_vat", "ge_vat", "gh_tin", "de_stn", "gb_vat", "gn_nif", "hk_br", "hu_tin", "is_vat", "in_gst", "id_npwp", "il_vat", "jp_cn", "jp_rn", "jp_trn", "kz_bin", "ke_pin", "kg_tin", "la_tin", "li_uid", "li_vat", "my_frp", "my_itn", "my_sst", "mr_nif", "mx_rfc", "md_vat", "me_pib", "ma_vat", "np_pan", "nz_gst", "ng_tin", "mk_vat", "no_vat", "no_voec", "om_vat", "pe_ruc", "ph_tin", "ro_tin", "ru_inn", "ru_kpp", "sa_vat", "sn_ninea", "rs_pib", "sg_gst", "sg_uen", "si_tin", "za_vat", "kr_brn", "es_cif", "ch_uid", "ch_vat", "tw_vat", "tj_tin", "tz_vat", "th_vat", "tr_tin", "ug_tin", "ua_vat", "ae_trn", "us_ein", "uy_ruc", "uz_tin", "uz_vat", "ve_rif", "vn_tin", "zm_tin", "zw_tin", "sr_fin" ], "example": "eu_vat", "type": "string" }, "tax_id_value": { "description": "Tax ID value, for example `DE123456789`.", "example": "DE123456789", "type": "string" } }, "required": [ "tax_id_type", "tax_id_value" ], "type": "object" }, "type": "array" }, "tax_remitted_by": { "description": "Determines whether Whop or the account calculates and remits tax. The account must provide a supported-country business address when it self-remits.", "enum": [ "whop", "self", "none" ], "example": "self", "type": "string" }, "tax_type": { "description": "Determines whether tax is included in the listed price or added at checkout.", "enum": [ "inclusive", "exclusive" ], "example": "inclusive", "type": "string" }, "three_ds_level": { "description": "Account-level 3D Secure behavior. Set `mandate_challenge` to require cardholder verification on supported card payments, or `null` to use the standard checkout flow.", "enum": [ "mandate_challenge" ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "description": "The display name of the account.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image.", "example": true, "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 has an unsupported enum value" }, "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" ] }, "x-whop-surface": "native" }, "/accounts/{id}/form_company": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Starts an LLC or C-Corp formation for a business account. Defaults to an LLC; set `entity_type` to `c_corp` to form a C-Corp, which additionally requires `share_structure` and officer `roles` on every founder. On submission, the application is validated and the response returns a hosted checkout URL. Once paid, the filing is submitted. Track progress through the account's [`company_formation`](/api-reference/beta/accounts/retrieve-account) field on Retrieve Account.", "operationId": "formCompany", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "business_address": { "city": "Austin", "country": "US", "line1": "4180 Burnet Rd", "line2": "Suite 2", "postal_code": "78756", "state": "TX" }, "business_name": "Shine Time Auto Detailing", "business_phone": "+15125550142", "business_type": "brick_and_mortar", "business_website": "https://shinetime.example", "entity_suffix": "LLC", "entity_type": "llc", "expedite_ein": true, "formation_state": "TX", "founders": [ { "address": { "city": "Austin", "country": "US", "line1": "907 Ridgemont Dr", "line2": "Apt 4", "postal_code": "78704", "state": "TX" }, "date_of_birth": "1988-03-14", "email": "marcus@shinetime.example", "first_name": "Marcus", "is_primary": true, "last_name": "Webb", "ownership_percentage": 100, "phone": "+15125550142", "roles": [ "president" ], "ssn": "123-45-6789" } ], "industry_group": "automotive", "industry_type": "car_wash", "share_structure": { "number_of_shares": 123, "value": 123 }, "use_registered_agent": true }, "properties": { "business_address": { "description": "Company mailing address. Required unless `use_registered_agent` is `true`.", "properties": { "city": { "example": "Austin", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": "string" }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": "string" }, "state": { "description": "State or region code, for example `CA`.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "state", "postal_code", "country" ], "type": "object" }, "business_name": { "description": "Legal name for the new company.", "example": "Shine Time Auto Detailing", "type": "string" }, "business_phone": { "description": "Business phone number in E.164 format, for example `+12125550100`. Required unless `use_registered_agent` is `true`.", "example": "+xxxxxxxxxxx", "type": "string" }, "business_type": { "description": "High-level business category, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary).", "example": "brick_and_mortar", "type": "string" }, "business_website": { "description": "Company website URL.", "example": "https://shinetime.example", "type": "string" }, "entity_suffix": { "description": "Legal entity ending appended to `business_name`. LLC formations accept `LLC`, `L.L.C`, `L.L.C.` or `Limited Liability Company` and default to `LLC`; C-Corp formations accept `Inc`, `Inc.`, `Incorporated`, `Corp.`, `Corporation`, `C Corp`, `C Corporation`, `CCorp` or `Company` and default to `Inc.`. Unrecognized values fall back to the default for the entity type.", "enum": [ "LLC", "L.L.C", "L.L.C.", "Limited Liability Company", "Inc", "Inc.", "Incorporated", "Corp.", "Corporation", "C Corp", "C Corporation", "CCorp", "Company" ], "example": "Limited Liability Company", "type": "string", "x-enumNames": [ "LLC", "L_L_C", "L_L_C_", "Limited_Liability_Company", "Inc", "Inc_", "Incorporated", "Corp_", "Corporation", "C_Corp", "C_Corporation", "CCorp", "Company" ] }, "entity_type": { "description": "Legal entity type to form. Defaults to `llc`.", "enum": [ "llc", "c_corp" ], "example": "c_corp", "type": "string" }, "expedite_ein": { "description": "Request expedited EIN processing for an additional fee. Available only when no founder supplies an SSN.", "example": true, "type": "boolean" }, "formation_state": { "description": "Two-letter code of the US state (or `DC`) to form the company in.", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "example": "TX", "type": "string" }, "founders": { "description": "The company's founders. Exactly one must be marked `is_primary` — the responsible party for the filing.", "items": { "properties": { "address": { "description": "Founder's personal address.", "properties": { "city": { "example": "Austin", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "907 Ridgemont Dr", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Apt 4", "type": "string" }, "postal_code": { "description": "Postal or ZIP code.", "example": "78704", "type": "string" }, "state": { "description": "State or region code, for example `CA`.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "state", "postal_code", "country" ], "type": "object" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "email": { "example": "marcus@shinetime.example", "type": "string" }, "first_name": { "example": "Marcus", "type": "string" }, "is_primary": { "description": "Marks the responsible party for the filing. Exactly one founder must be primary.", "example": true, "type": "boolean" }, "last_name": { "example": "Webb", "type": "string" }, "ownership_percentage": { "description": "The founder's ownership share: greater than `0`, at most `100`. Shares across founders must total `100`. Required when `entity_type` is `llc`; ignored for C-Corps.", "example": 100, "type": "number" }, "phone": { "description": "Phone number in E.164 format, for example `+12125550100`.", "example": "+xxxxxxxxxxx", "type": "string" }, "roles": { "description": "Officer roles held by the member — one member can hold several. Required (at least one role) for every member when `entity_type` is `c_corp`; ignored for LLCs. Across all members every role must be covered; `president`, `secretary` and `treasurer` may each be held by only one member, while `director` may repeat.", "items": { "enum": [ "president", "secretary", "treasurer", "director" ], "example": "treasurer", "type": "string" }, "type": "array" }, "ssn": { "description": "The founder's US Social Security Number. Leave empty if the founder is not a US resident. Non-US founders can request expedited EIN processing via the `expedite_ein` option.", "example": "123-45-6789", "type": "string" } }, "required": [ "is_primary", "first_name", "last_name", "email", "phone", "address" ], "type": "object" }, "type": "array" }, "industry_group": { "description": "Industry group, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary).", "example": "automotive", "type": "string" }, "industry_type": { "description": "Specific industry vertical, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary).", "example": "car_wash", "type": "string" }, "share_structure": { "description": "Authorized share structure. Required when `entity_type` is `c_corp`; ignored for LLCs.", "properties": { "number_of_shares": { "description": "Number of shares the company authorizes. Must be greater than `0`.", "example": 1000, "type": "integer" }, "value": { "description": "Par value per share, in USD. Must be greater than `0`; fractional values like `0.01` are allowed.", "example": 100, "type": "number" } }, "required": [ "number_of_shares", "value" ], "type": "object" }, "use_registered_agent": { "description": "Use the registered agent's address as the company address instead of `business_address`.", "example": true, "type": "boolean" } }, "required": [ "business_name", "formation_state", "business_type", "industry_group", "industry_type", "founders" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "checkout_session_id": { "description": "Checkout session ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "checkout_url": { "description": "Hosted checkout URL. Send the buyer here to pay for the formation; the filing is submitted once payment completes.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": "string" }, "currency": { "description": "Always `usd`.", "example": "usd", "type": "string" }, "total": { "description": "Total due at checkout in USD cents.", "example": 40000, "type": "integer" } }, "required": [ "checkout_url", "checkout_session_id", "total", "currency" ], "type": "object" } } }, "description": "application accepted and checkout created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid submission" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential cannot manage the account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "incorporation:write" ] } ], "summary": "Form Company", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/{id}/suspend": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Connected account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Suspends a connected account directly owned by the authenticated platform account. This cannot suspend the platform account itself or an account owned by another platform.", "operationId": "suspendAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "Connected account suspended." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "API key lacks the child-account suspension scope." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Connected account not found." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:suspend_child" ] } ], "summary": "Suspend a Connected Account", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/{id}/transfer_ownership": { "post": { "description": "Transfers ownership of the account to another user, identified by user ID or email address. If the recipient already holds the owner role, ownership moves immediately; otherwise they get an invite and ownership moves when they accept.", "operationId": "transferAccountOwnership", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "as_partner": { "description": "If true, the current owner is credited as the account's Whop partner, earning partner commission on its sales. Requires the current owner to already be an enrolled Whop partner. Skipped if the account already has an active partner.", "example": true, "type": "boolean" }, "identifier": { "description": "The user to transfer ownership to: a user ID (`user_*`) or an email address. An email address with no Whop account yet is sent an invite to create one.", "example": "marcus@shinetime.example", "type": "string" }, "message": { "description": "A note from the partner, shown as a quote in the invite email and signed with their name. Requires `as_partner`; sending it on an ordinary transfer is a 400. Omit it and the email sends without a note.", "example": "Hey — set this up after our call on Tuesday. Ping me anytime.", "maxLength": 500, "type": "string" } }, "required": [ "identifier" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Ownership transferred." }, "201": { "content": { "application/json": { "schema": { "properties": { "invitation_sent": { "example": true, "type": "boolean" }, "object": { "enum": [ "team_member_invite" ], "example": "team_member_invite", "type": "string" } }, "required": [ "object", "invitation_sent" ], "type": "object" } } }, "description": "Ownership transfer invite sent — the recipient must accept before ownership moves." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "API key lacks the ownership transfer scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:transfer_ownership" ] } ], "summary": "Transfer Account Ownership", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/ad_campaigns": { "get": { "description": "Lists the ad campaigns for an account, with stats over the requested window.", "operationId": "listAdCampaigns", "parameters": [ { "description": "The account the campaigns belong to. Defaults to the account-scoped key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return campaigns with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "active", "paused", "payment_failed" ], "type": "string" } }, { "description": "Filter campaigns by a title or ID substring.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at", "spend", "impressions", "reach", "clicks", "link_clicks", "unique_clicks", "frequency", "click_through_rate", "results", "cost_per_mille", "cost_per_click", "cost_per_result", "return_on_ad_spend" ], "type": "string" } }, { "description": "The sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return campaigns created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return campaigns created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Start of the stats window. Defaults to all-time.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window. Defaults to now.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "The number of campaigns to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of campaigns to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdCampaign" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "ad campaigns listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id missing and unresolvable" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List Ad Campaigns", "tags": [ "Ad Campaigns" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad campaign for an account.", "operationId": "createAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to create the campaign under. Defaults to the account-scoped key's own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, `maximum_target` never bids above a cap. Only for campaigns that own the budget.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "The campaign's budget, in the ad account's currency. Required when budget_optimization is `ad_campaign`; omit when each ad group sets its own budget.", "example": 25.0, "type": "number" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`). Defaults to `ad_group`.", "enum": [ "ad_campaign", "ad_group" ], "example": "ad_campaign", "type": "string" }, "budget_type": { "description": "Whether the budget is spent per day (`daily`) or over the campaign's full run (`lifetime`). Defaults to `daily`.", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). Only for campaigns that own the budget.", "example": 4.5, "type": "number" }, "ends_at": { "description": "When the campaign stops delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "objective": { "description": "The goal the campaign optimizes toward.", "enum": [ "awareness", "traffic", "engagement", "leads", "sales" ], "example": "leads", "type": "string" }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta" ], "example": "meta", "type": "string" }, "special_ad_categories": { "description": "Regulated categories the campaign falls under. Ads in these categories are subject to extra targeting restrictions.", "items": { "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "starts_at": { "description": "When the campaign starts delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "title": { "description": "The title of the campaign.", "example": "Now hiring mobile detailers — Austin", "type": "string" } }, "required": [ "title", "platform", "objective" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unsupported platform" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Create an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}": { "delete": { "description": "Deletes an ad campaign and archives it on the ad platform (cascades to ad groups and ads).", "operationId": "deleteAdCampaign", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted ad campaign.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "ad campaign deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "get": { "description": "Retrieves a single ad campaign with stats over the requested window.", "operationId": "retrieveAdCampaign", "parameters": [ { "description": "Start of the stats window.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone the stats window is interpreted in. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an ad campaign's editable fields (title, budget, schedule, bid strategy, special ad categories, and, before launch, budget type and budget optimization), and launches a draft campaign by setting status to active. Objective and desired cost per result are fixed at creation and cannot be changed.", "operationId": "updateAdCampaign", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, `maximum_target` never bids above a cap. Switching to `minimum_cost` clears the cap amounts stored on the campaign's ad groups. Only for campaigns that own the budget.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "The campaign budget, in the account's currency. Interpreted as daily or lifetime per the campaign's budget type, including a budget_type sent in the same request.", "example": 40.0, "type": "number" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`). Only changeable before the campaign is live on the ad network; switching to `ad_campaign` requires budget_amount in the same request, and switching to `ad_group` clears the campaign budget.", "enum": [ "ad_campaign", "ad_group" ], "example": "ad_campaign", "type": "string" }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`). Only changeable while the campaign is a draft; send budget_amount in the same request so the amount lands on the new type.", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "ends_at": { "description": "When the campaign stops delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "special_ad_categories": { "description": "Regulated categories the campaign falls under. Editable on any campaign, draft or launched; pass an empty array to clear.", "items": { "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "starts_at": { "description": "When the campaign starts delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Set to active to launch a draft campaign (moderates and pushes it live). Live-campaign pause and resume use the pause and unpause actions.", "enum": [ "active" ], "example": "active", "type": "string" }, "title": { "description": "The name of the campaign.", "example": "Now hiring mobile detailers — Austin & Round Rock", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign updated" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Creates copies of the campaign in `duplicating` status and returns them; each copy transitions to `draft` once duplication completes. Poll each returned campaign until it leaves `duplicating` — a copy that could not be completed is deleted and returns 404.", "operationId": "duplicateAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "Number of copies to create (1-10). Defaults to 1.", "example": 2, "type": "integer" }, "preserve_engagement": { "description": "Whether the copied ads keep the original posts' engagement (likes, comments, shares). Defaults to false.", "example": true, "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdCampaign" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "ad campaign duplication started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a duplication is already running for this campaign" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Duplicate an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses an active ad campaign.", "operationId": "pauseAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/retry_payment": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Retries billing for an ad campaign whose payment previously failed.", "operationId": "retryAdCampaignPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "payment retried" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "campaign is not in payment_failed status" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Retry a Failed Ad Campaign Payment", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes a paused ad campaign.", "operationId": "unpauseAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign unpaused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_groups": { "get": { "description": "Lists ad groups for the account, newest first.", "operationId": "listAdGroups", "parameters": [ { "description": "Account whose ad groups to list. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to ad groups in this campaign.", "in": "query", "name": "ad_campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to ad groups in these campaigns (max 100). Repeat the parameter for each id (ad_campaign_ids=a&ad_campaign_ids=b).", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Filter to ad groups with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused", "rejected", "duplicating" ], "type": "string" } }, { "description": "Filter ad groups by a title or ID substring.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at", "spend", "impressions", "reach", "clicks", "link_clicks", "unique_clicks", "frequency", "click_through_rate", "results", "cost_per_mille", "cost_per_click", "cost_per_result", "return_on_ad_spend" ], "type": "string" } }, { "description": "The sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return ad groups created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return ad groups created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Start of the stats window. Defaults to all-time.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window. Defaults to now.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "The number of ad groups to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of ad groups to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdGroup" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "ad groups listed" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List Ad Groups", "tags": [ "Ad Groups" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad group (ad set) in a campaign.", "operationId": "createAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ad_campaign_id": { "description": "The ad campaign to create the ad group in, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiencesBody", "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "This ad group's budget, in the ad account's currency. Omit when the budget is set on the campaign instead.", "example": 40.0, "type": "number" }, "budget_type": { "description": "Whether budget_amount is spent per day (`daily`) or over the ad group's full run (`lifetime`).", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. The lead form itself is set on the ad.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms" ], "example": "website", "type": "string" }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographicsBody", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`).", "example": 35.0, "type": "number" }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargetingBody", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories. Send the complete intended state — a section you omit is cleared." }, "devices": { "$ref": "#/components/schemas/AdGroupDevicesBody", "description": "Device platforms and operating systems to target." }, "dynamic_creative": { "description": "Let the ad platform automatically mix and match this ad group's creatives and copy to find the best-performing combinations. Set at creation; can't be changed afterward.", "example": false, "type": "boolean" }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. Omit to run until paused.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective.", "properties": { "maximum_impressions": { "description": "Most times one person can be shown ads from this ad group within the window.", "example": 3, "type": "integer" }, "per_days": { "description": "Length of the rolling window, in days.", "example": 7, "type": "integer" } }, "type": "object" }, "languages": { "description": "Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.", "items": { "example": "en", "type": "string" }, "type": "array" }, "message_apps": { "description": "Apps the conversation opens in. Required when setting `conversion_location` to `messaging`, and rejected unless the ad group's conversion location is `messaging`.", "items": { "enum": [ "messenger", "instagram", "whatsapp" ], "example": "whatsapp", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day.", "example": 20.0, "type": "number" }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement" ], "example": "reach", "type": "string" }, "placements": { "anyOf": [ { "enum": [ "automatic" ], "example": "automatic", "type": "string" }, { "items": { "properties": { "platform": { "description": "Platform the ads run on.", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "example": "instagram", "type": "string" }, "positions": { "description": "Positions to target within the platform, such as `feed` or `story`. Omit to target all of the platform's positions.", "items": { "example": "stream", "type": "string" }, "type": "array" } }, "required": [ "platform" ], "type": "object" }, "type": "array" } ], "description": "`automatic` to let the ad platform choose placements, or the list of platforms and positions to target. Omit a platform's positions to target all of them.\n\nValid positions per platform:\n\n- `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`, `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `biz_disco_feed`\n- `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `profile_reels`, `ig_search`\n- `messenger`: `story`\n- `audience_network`: `classic`, `rewarded_video`\n- `threads`: `threads_stream`\n- `whatsapp`: `status`" }, "regions": { "$ref": "#/components/schemas/AdGroupRegionsBody", "description": "Locations to target and exclude." }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. Omit to start as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Initial status (default: `active`).", "enum": [ "active", "paused" ], "example": "paused", "type": "string" }, "title": { "description": "The display name of the ad group.", "example": "North America — brand prospecting", "type": "string" } }, "required": [ "ad_campaign_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group created" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Create an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/estimate_reach": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Estimates how many people a draft targeting spec can reach, before an ad group is created. The body takes the same targeting fields as creating an ad group — `regions`, `demographics`, `detailed_targeting`, `audiences`, `languages`, and `devices` — and nothing is persisted.", "operationId": "estimateAdGroupReach", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to estimate on behalf of. Defaults to the authenticated account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiencesBody", "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic." }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographicsBody", "description": "Age, gender, and automatic-audience targeting." }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargetingBody", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. At most 100 entries per section." }, "devices": { "$ref": "#/components/schemas/AdGroupDevicesBody", "description": "Device platforms and operating systems to target." }, "languages": { "description": "Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.", "items": { "example": "en", "type": "string" }, "type": "array" }, "platform": { "description": "The ad network the estimate runs on.", "enum": [ "meta" ], "example": "meta", "type": "string" }, "regions": { "$ref": "#/components/schemas/AdGroupRegionsBody", "description": "Locations to target and exclude." } }, "required": [ "platform" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachEstimate" } } }, "description": "reach estimated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no ad account is available for estimates" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "key lacks the required scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Estimate Ad Group Reach", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/targeting_options": { "get": { "description": "Searches the ad platform's targeting taxonomy for options to target an ad group with. Each result comes back in the exact shape the ad-group body accepts for its `type`, so it can be used in `detailed_targeting`, `regions`, or `languages` as-is. A blank `query` browses the small fixed lists (behaviors, browse demographic categories, languages); interests, work employers, job titles, schools, majors, and locations need a search term.", "operationId": "searchAdGroupTargetingOptions", "parameters": [ { "description": "Account to search on behalf of. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The ad network whose targeting taxonomy to search.", "in": "query", "name": "platform", "required": true, "schema": { "enum": [ "meta" ], "type": "string" } }, { "description": "The search term. Blank browses the fixed lists; interests, work employers, job titles, schools, majors, and locations return nothing without one.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Kinds of targeting options to search. Defaults to all of them.", "explode": true, "in": "query", "name": "types", "required": false, "schema": { "items": { "enum": [ "interests", "behaviors", "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors", "languages", "locations" ], "example": "interests", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Narrow location results to these kinds of places. Only applies when `types` includes `locations`.", "explode": true, "in": "query", "name": "location_types", "required": false, "schema": { "items": { "enum": [ "country", "region", "city", "zip", "neighborhood", "subcity", "medium_geo_area" ], "example": "country", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Narrow location results to one country, as an ISO 3166-1 code such as `US`. Only applies when `types` includes `locations`.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Maximum number of results per requested type.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 500, "type": "integer" } }, { "description": "The campaign's declared special ad categories. Under `housing`, `employment`, or `financial_products` the ad platform allows interests only, drawn from a short approved list, so results are narrowed to what such a campaign can launch with and other kinds return nothing. Blank `query` browses that approved list instead of the usual fixed lists.", "explode": true, "in": "query", "name": "special_ad_categories", "required": false, "schema": { "items": { "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "housing", "type": "string" }, "type": "array" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TargetingOption" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "types narrows the search and accepts a comma-separated list" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "location filters need locations in types" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "key lacks the required scope" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Search Targeting Options", "tags": [ "Ad Groups" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/ad_groups/{id}": { "delete": { "description": "Deletes an ad group.", "operationId": "deleteAdGroup", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted ad group.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "ad group deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete an Ad Group", "tags": [ "Ad Groups" ] }, "get": { "description": "Retrieves a single ad group.", "operationId": "retrieveAdGroup", "parameters": [ { "description": "Start of the stats window.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone the stats window is interpreted in. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve an Ad Group", "tags": [ "Ad Groups" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an ad group's editable fields. Only the keys you send are changed.", "operationId": "updateAdGroup", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "audiences": { "$ref": "#/components/schemas/AdGroupAudiencesBody", "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "This ad group's budget, in the ad account's currency. Omit when the budget is set on the campaign instead.", "example": 40.0, "type": "number" }, "budget_type": { "description": "Whether budget_amount is spent per day (`daily`) or over the ad group's full run (`lifetime`).", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. The lead form itself is set on the ad.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms" ], "example": "website", "type": "string" }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographicsBody", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`).", "example": 35.0, "type": "number" }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargetingBody", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories. Send the complete intended state — a section you omit is cleared." }, "devices": { "$ref": "#/components/schemas/AdGroupDevicesBody", "description": "Device platforms and operating systems to target." }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. Omit to run until paused.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective.", "properties": { "maximum_impressions": { "description": "Most times one person can be shown ads from this ad group within the window.", "example": 3, "type": "integer" }, "per_days": { "description": "Length of the rolling window, in days.", "example": 7, "type": "integer" } }, "type": "object" }, "languages": { "description": "Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.", "items": { "example": "en", "type": "string" }, "type": "array" }, "message_apps": { "description": "Apps the conversation opens in. Required when setting `conversion_location` to `messaging`, and rejected unless the ad group's conversion location is `messaging`.", "items": { "enum": [ "messenger", "instagram", "whatsapp" ], "example": "whatsapp", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day.", "example": 20.0, "type": "number" }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement" ], "example": "reach", "type": "string" }, "placements": { "anyOf": [ { "enum": [ "automatic" ], "example": "automatic", "type": "string" }, { "items": { "properties": { "platform": { "description": "Platform the ads run on.", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "example": "instagram", "type": "string" }, "positions": { "description": "Positions to target within the platform, such as `feed` or `story`. Omit to target all of the platform's positions.", "items": { "example": "stream", "type": "string" }, "type": "array" } }, "required": [ "platform" ], "type": "object" }, "type": "array" } ], "description": "`automatic` to let the ad platform choose placements, or the list of platforms and positions to target. Omit a platform's positions to target all of them.\n\nValid positions per platform:\n\n- `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`, `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `biz_disco_feed`\n- `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `profile_reels`, `ig_search`\n- `messenger`: `story`\n- `audience_network`: `classic`, `rewarded_video`\n- `threads`: `threads_stream`\n- `whatsapp`: `status`" }, "regions": { "$ref": "#/components/schemas/AdGroupRegionsBody", "description": "Locations to target and exclude." }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. Omit to start as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Initial status (default: `active`).", "enum": [ "active", "paused" ], "example": "paused", "type": "string" }, "title": { "description": "The display name of the ad group.", "example": "North America — brand prospecting", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group updated" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Creates copies of the ad group in `duplicating` status and returns them — into its own campaign, or into target_ad_campaign_id (which must belong to the same account and be compatible with the ad group's targeting and goals); each copy transitions to its final status (matching the source's active/paused state) once duplication completes. Poll each returned ad group until it leaves `duplicating` — a copy that could not be completed is deleted and returns 404.", "operationId": "duplicateAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "Number of copies to create (1-10). Defaults to 1.", "example": 2, "type": "integer" }, "preserve_engagement": { "description": "Whether the copied ads keep the original posts' engagement (likes, comments, shares). Defaults to false.", "example": true, "type": "boolean" }, "target_ad_campaign_id": { "description": "Campaign to duplicate into. Defaults to the ad group's own campaign.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdGroup" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "ad group duplication started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a duplication is already running for this ad group" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Duplicate an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses delivery of an ad group.", "operationId": "pauseAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes delivery of a paused ad group.", "operationId": "unpauseAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group unpaused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "breakdown", "required": false, "schema": { "$ref": "#/components/schemas/AdReportBreakdownLevels", "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." }, "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" }, "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" }, "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": { "$ref": "#/components/schemas/Granularities", "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." }, "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" }, "429": { "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": "Too many requests" }, "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": "Lists the ads for an account, with stats over the requested window.", "operationId": "listAds", "parameters": [ { "description": "The account the ads belong to. Defaults to the account-scoped key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads in this ad campaign.", "in": "query", "name": "ad_campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads in these ad campaigns (max 100). Repeat the parameter for each id (ad_campaign_ids=a&ad_campaign_ids=b).", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return ads in this ad group.", "in": "query", "name": "ad_group_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads in these ad groups (max 100). Repeat the parameter for each id (ad_group_ids=a&ad_group_ids=b).", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "items": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return ads with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused", "in_review", "rejected" ], "type": "string" } }, { "description": "Filter ads by a title or ID substring.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at", "spend", "impressions", "reach", "clicks", "link_clicks", "unique_clicks", "frequency", "click_through_rate", "results", "cost_per_mille", "cost_per_click", "cost_per_result", "return_on_ad_spend" ], "type": "string" } }, { "description": "The sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return ads created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Start of the stats window. Defaults to all-time.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window. Defaults to now.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "The number of ads to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of ads to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "ads listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id missing and unresolvable" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List Ads", "tags": [ "Ads" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad in an ad group.", "operationId": "createAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ad_group": { "description": "An inline ad group to create (same shape as POST /ad_groups, including ad_campaign_id). Creates the ad group and the ad together. Provide this OR ad_group_id.", "example": { "ad_campaign_id": "adcamp_xxxxxxxxxxxxxx", "budget_amount": 60.0, "optimization_goal": "conversions", "title": "Austin — ceramic coating buyers" }, "type": "object" }, "ad_group_id": { "description": "The existing ad group to create the ad in. Provide this OR ad_group, not both.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "apply_now", "book_now", "call_now", "contact_us", "download", "get_directions", "get_offer", "get_quote", "learn_more", "listen_now", "message_page", "no_button", "open_link", "order_now", "request_time", "see_details", "see_menu", "send_updates", "shop_now", "sign_up", "subscribe", "watch_more" ], "example": "message_page", "type": "string" }, "creatives": { "description": "The ad's creative assets. Each entry is an uploaded file id with an optional format; omit format for the original asset. Two or more entries with no format become a carousel (2-10 attachments), in order, sharing the ad's copy.", "items": { "properties": { "crop": { "description": "The saved crop window for this creative, in source image pixels. Omit it for the original asset or for a format that has not been cropped.", "properties": { "height": { "example": 1000, "type": "number" }, "width": { "example": 1000, "type": "number" }, "x": { "example": 40, "type": "number" }, "y": { "example": 0, "type": "number" } }, "type": "object" }, "format": { "enum": [ "square", "vertical", "horizontal" ], "example": "square", "type": "string" }, "id": { "description": "Uploaded file ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "descriptions": { "description": "The description variants shown on the ad.", "items": { "example": "Two-stage paint correction included", "type": "string" }, "type": "array" }, "existing_post_id": { "description": "Promote a post you already published instead of uploading creatives — a Facebook post or Instagram media id. Mutually exclusive with creatives. Pair with post_source.", "example": "1784512345678901", "type": "string" }, "headlines": { "description": "The headline variants shown on the ad.", "items": { "example": "Showroom shine, guaranteed", "type": "string" }, "type": "array" }, "lead_form": { "description": "Instant lead form for the ad. Only allowed when the ad group's conversion_location is an instant-form destination (instant_forms, instant_forms_and_messenger, website_and_instant_forms). Mutually exclusive with lead_form_id.", "properties": { "completion": { "description": "Optional completion screen shown after submission; url sets the follow-up website button.", "properties": { "button_text": { "example": "See our work", "type": "string" }, "description": { "example": "We book coatings two days out, so pick a slot when we ring.", "type": "string" }, "headline": { "example": "Thanks — we will call you today", "type": "string" }, "url": { "example": "https://shinetime.example/gallery", "type": "string" } }, "type": "object" }, "disclaimer": { "description": "Optional custom consent disclaimer with checkboxes.", "properties": { "body": { "example": "Ceramic coating requires the vehicle for two days.", "type": "string" }, "checkboxes": { "items": { "properties": { "checked_by_default": { "example": false, "type": "boolean" }, "key": { "example": "two_days", "type": "string" }, "required": { "example": true, "type": "boolean" }, "text": { "example": "I can leave my vehicle for two days", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "example": "Before you submit", "type": "string" } }, "type": "object" }, "form_type": { "description": "more_volume (default) is quickest to submit; higher_intent adds a confirmation step.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "intro": { "description": "Optional intro screen shown before the questions.", "properties": { "description": { "example": "Tell us about your vehicle and we will send a fixed price.", "type": "string" }, "headline": { "example": "Get a ceramic coating quote", "type": "string" } }, "type": "object" }, "name": { "description": "Internal name for the form. Auto-generated if omitted.", "example": "Ceramic coating quote requests", "type": "string" }, "phone_verification": { "description": "Require SMS verification of the phone number (higher_intent forms).", "example": true, "type": "boolean" }, "privacy_policy": { "description": "Your privacy policy. url is required by the ad platform.", "properties": { "link_text": { "example": "Shine Time privacy policy", "type": "string" }, "url": { "example": "https://shinetime.example/privacy", "type": "string" } }, "type": "object" }, "questions": { "description": "The questions on the form. Standard prefill types need only a type; a custom question needs a label and a format (plus options for multiple_choice). Options carry an optional key and answer-routing logic.", "items": { "properties": { "format": { "enum": [ "short_answer", "multiple_choice", "appointment" ], "example": "multiple_choice", "type": "string" }, "label": { "example": "What vehicle are we detailing?", "type": "string" }, "options": { "items": { "properties": { "key": { "example": "sedan", "type": "string" }, "logic": { "properties": { "action": { "enum": [ "go_to_question", "submit_form", "close_form" ], "example": "go_to_question", "type": "string" }, "target_end_page_index": { "example": 0, "type": "integer" }, "target_question_index": { "example": 3, "type": "integer" } }, "type": "object" }, "value": { "example": "Sedan or coupe", "type": "string" } }, "type": "object" }, "type": "array" }, "type": { "enum": [ "email", "phone", "full_name", "first_name", "last_name", "city", "state", "zip", "country", "street_address", "job_title", "company_name", "work_email", "work_phone_number", "dob", "gender", "marital_status", "relationship_status", "military_status", "date_time", "custom" ], "example": "phone", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "lead_form_id": { "description": "Use an existing instant form instead of creating one — the form's platform ID, from a form already on the ad's Facebook page. Only allowed when the ad group's conversion_location is an instant-form destination. Mutually exclusive with lead_form.", "example": "1037724182084885", "type": "string" }, "messaging_config": { "description": "Click-to-message welcome copy: the greeting (message) and the ice-breaker prompt (keyword).", "properties": { "keyword": { "example": "Book an interior deep clean", "type": "string" }, "message": { "example": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote.", "type": "string" } }, "type": "object" }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": false, "type": "boolean" }, "post_source": { "description": "Identifies the network that owns `existing_post_id`. The source is inferred from the ID shape when omitted.", "enum": [ "facebook", "instagram" ], "example": "instagram", "type": "string" }, "primary_texts": { "description": "The primary text variants shown in the ad body.", "items": { "example": "Three-year ceramic coating, booked online in under a minute.", "type": "string" }, "type": "array" }, "social_accounts": { "description": "The social accounts the ad runs under — a connected Facebook page and, optionally, an Instagram profile.", "items": { "properties": { "id": { "description": "Social account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "description": "The display name of the ad.", "example": "Interior deep clean — DM us", "type": "string" }, "url": { "description": "The URL the ad links to. Query parameters are merged into url_parameters, so the stored URL is always bare.", "example": "https://shinetime.example/ceramic-coating", "type": "string" }, "url_parameters": { "description": "Query parameters to append to the destination URL, keyed by parameter name. Merged with any query string on `url`. Whop adds its own click-attribution parameters; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": { "ref": "spring" }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad created from an existing post" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Whop pixel not installed on the destination" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Create an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}": { "delete": { "description": "Deletes an ad.", "operationId": "deleteAd", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted ad.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "ad deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete an Ad", "tags": [ "Ads" ] }, "get": { "description": "Retrieves a single ad with stats over the requested window.", "operationId": "retrieveAd", "parameters": [ { "description": "Start of the stats window.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone the stats window is interpreted in. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve an Ad", "tags": [ "Ads" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an ad's editable fields.", "operationId": "updateAd", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "apply_now", "book_now", "call_now", "contact_us", "download", "get_directions", "get_offer", "get_quote", "learn_more", "listen_now", "message_page", "no_button", "open_link", "order_now", "request_time", "see_details", "see_menu", "send_updates", "shop_now", "sign_up", "subscribe", "watch_more" ], "example": "learn_more", "type": "string" }, "creatives": { "description": "The ad's creative assets. Each entry is an uploaded file id with an optional format; omit format for the original asset. Replaces a live ad's creative on the platform. Two or more entries with no format replace it with a carousel (2-10 attachments), in order, sharing the ad's copy.", "items": { "properties": { "crop": { "description": "The saved crop window for this creative, in source image pixels. Omit it for the original asset or for a format that has not been cropped.", "properties": { "height": { "example": 1920, "type": "number" }, "width": { "example": 1080, "type": "number" }, "x": { "example": 0, "type": "number" }, "y": { "example": 120, "type": "number" } }, "type": "object" }, "format": { "enum": [ "square", "vertical", "horizontal" ], "example": "vertical", "type": "string" }, "id": { "description": "Uploaded file ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "descriptions": { "description": "The description variants shown on the ad.", "items": { "example": "Paint correction included", "type": "string" }, "type": "array" }, "existing_post_id": { "description": "Promote a post you already published instead of uploading creatives — a Facebook post or Instagram media id. Mutually exclusive with creatives. Pair with post_source.", "example": "xxxxxxxxxxxxxxxx_98765", "type": "string" }, "headlines": { "description": "The headline variants shown on the ad.", "items": { "example": "Austin's mobile detailers", "type": "string" }, "type": "array" }, "lead_form": { "description": "Instant lead form for the ad. Only allowed when the ad group's conversion_location is an instant-form destination (instant_forms, instant_forms_and_messenger, website_and_instant_forms). Mutually exclusive with lead_form_id.", "properties": { "completion": { "description": "Optional completion screen shown after submission; url sets the follow-up website button.", "properties": { "button_text": { "example": "See our work", "type": "string" }, "description": { "example": "We book coatings two days out, so pick a slot when we ring.", "type": "string" }, "headline": { "example": "Thanks — we will call you today", "type": "string" }, "url": { "example": "https://shinetime.example/gallery", "type": "string" } }, "type": "object" }, "disclaimer": { "description": "Optional custom consent disclaimer with checkboxes.", "properties": { "body": { "example": "Ceramic coating requires the vehicle for two days.", "type": "string" }, "checkboxes": { "items": { "properties": { "checked_by_default": { "example": false, "type": "boolean" }, "key": { "example": "two_days", "type": "string" }, "required": { "example": true, "type": "boolean" }, "text": { "example": "I can leave my vehicle for two days", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "example": "Before you submit", "type": "string" } }, "type": "object" }, "form_type": { "description": "more_volume (default) is quickest to submit; higher_intent adds a confirmation step.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "intro": { "description": "Optional intro screen shown before the questions.", "properties": { "description": { "example": "Tell us about your vehicle and we will send a fixed price.", "type": "string" }, "headline": { "example": "Get a ceramic coating quote", "type": "string" } }, "type": "object" }, "name": { "description": "Internal name for the form. Auto-generated if omitted.", "example": "Ceramic coating quote requests", "type": "string" }, "phone_verification": { "description": "Require SMS verification of the phone number (higher_intent forms).", "example": true, "type": "boolean" }, "privacy_policy": { "description": "Your privacy policy. url is required by the ad platform.", "properties": { "link_text": { "example": "Shine Time privacy policy", "type": "string" }, "url": { "example": "https://shinetime.example/privacy", "type": "string" } }, "type": "object" }, "questions": { "description": "The questions on the form. Standard prefill types need only a type; a custom question needs a label and a format (plus options for multiple_choice). Options carry an optional key and answer-routing logic.", "items": { "properties": { "format": { "enum": [ "short_answer", "multiple_choice", "appointment" ], "example": "multiple_choice", "type": "string" }, "label": { "example": "What vehicle are we detailing?", "type": "string" }, "options": { "items": { "properties": { "key": { "example": "sedan", "type": "string" }, "logic": { "properties": { "action": { "enum": [ "go_to_question", "submit_form", "close_form" ], "example": "go_to_question", "type": "string" }, "target_end_page_index": { "example": 0, "type": "integer" }, "target_question_index": { "example": 3, "type": "integer" } }, "type": "object" }, "value": { "example": "Sedan or coupe", "type": "string" } }, "type": "object" }, "type": "array" }, "type": { "enum": [ "email", "phone", "full_name", "first_name", "last_name", "city", "state", "zip", "country", "street_address", "job_title", "company_name", "work_email", "work_phone_number", "dob", "gender", "marital_status", "relationship_status", "military_status", "date_time", "custom" ], "example": "phone", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "lead_form_id": { "description": "Use an existing instant form instead of creating one — the form's platform ID, from a form already on the ad's Facebook page. Only allowed when the ad group's conversion_location is an instant-form destination. Mutually exclusive with lead_form. Replaces a stored lead_form.", "example": "1037724182084885", "type": "string" }, "messaging_config": { "description": "Click-to-message welcome copy: the greeting (message) and the ice-breaker prompt (keyword).", "properties": { "keyword": { "example": "Get a ceramic coating quote", "type": "string" }, "message": { "example": "Hi! Which vehicle are we coating?", "type": "string" } }, "type": "object" }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": false, "type": "boolean" }, "post_source": { "description": "Identifies the network that owns `existing_post_id`. The source is inferred from the ID shape when omitted.", "enum": [ "facebook", "instagram" ], "example": "facebook", "type": "string" }, "primary_texts": { "description": "The primary text variants shown in the ad body.", "items": { "example": "Book a two-day ceramic coating and keep the shine for three years.", "type": "string" }, "type": "array" }, "social_accounts": { "description": "The social accounts the ad runs under — a connected Facebook page and, optionally, an Instagram profile.", "items": { "properties": { "id": { "description": "Social account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "description": "The display name of the ad.", "example": "Ceramic coating — spring hook v2", "type": "string" }, "url": { "description": "The URL the ad links to. Query parameters are merged into url_parameters, so the stored URL is always bare.", "example": "https://shinetime.example/ceramic-coating", "type": "string" }, "url_parameters": { "description": "Query parameters to append to the destination URL, keyed by parameter name. Merged with any query string on `url`. Whop adds its own click-attribution parameters; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": { "placement": "{{placement}}", "ref": "spring" }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad switched to an existing post" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Copies the ad into its own ad group, or into target_ad_group_id (which must belong to the same account and be compatible with the ad). Copies keep the source ad's active/paused state.", "operationId": "duplicateAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "Number of copies to create (1-10). Defaults to 1.", "example": 2, "type": "integer" }, "preserve_engagement": { "description": "Whether the copies keep the original post's engagement (likes, comments, shares). Defaults to false.", "example": true, "type": "boolean" }, "target_ad_group_id": { "description": "Ad group to duplicate into. Defaults to the ad's own ad group.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "ad duplicated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "target ad group on a different ad account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Duplicate an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses an active ad.", "operationId": "pauseAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes a paused ad.", "operationId": "unpauseAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad unpaused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for results. Defaults to descending." }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/AffiliatesSortableColumns", "description": "The field to sort results by." }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Search affiliates by username.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/Status", "description": "Filter by affiliate status (active or archived)." }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "override_type", "required": false, "schema": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "Filter by override type (standard or rev_share)." }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/api_keys": { "get": { "description": "Lists the API keys of an account or app, newest first. Responses never include the full secret — only its obfuscated form.", "operationId": "listApiKeys", "parameters": [ { "description": "The account (`biz_`) or app (`app_`) tag to list API keys for.", "in": "query", "name": "resource_id", "required": true, "schema": { "type": "string" } }, { "description": "The type of resource that owns the API keys.", "in": "query", "name": "resource_type", "required": true, "schema": { "enum": [ "account", "app" ], "type": "string" } }, { "description": "Only return API keys created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "Only return API keys created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "The number of API keys to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns API keys after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of API keys to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns API keys before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort API keys by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "api keys listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the resource type is not supported" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no resource with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "List API Keys", "tags": [ "API Keys" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an API key for an account or app. The response is the only place the full `secret_key` is returned — store it immediately. Requires a user session; API keys cannot manage API keys.", "operationId": "createApiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "Dated API version used when requests authenticated with this key omit the `Api-Version-Date` header. New keys default to the latest version.", "enum": [ "2025-01-01", "2026-06-08", "2026-06-09", "2026-06-20", "2026-07-01", "2026-07-08", "2026-07-08-1", "2026-07-18", "2026-07-20", "2026-07-22", "2026-07-23", "2026-07-25", "2026-07-26", "2026-07-27", "2026-07-29", "2026-07-29-1", "2026-07-31", "2026-08-03", "2026-08-05", "2026-08-05-1", "2026-08-10", "2026-08-12", "2026-08-13", "2026-08-14", "2026-08-21", "2026-08-21-1", "2026-08-25", "2026-08-25-1", "2026-08-25-2" ], "example": "2026-08-25-2", "type": "string" }, "expires_at": { "description": "When the API key should stop working, as an ISO 8601 timestamp. Omit (or pass `null` on update) for a key that never expires.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "ip_allowlist": { "description": "IPv4/IPv6 CIDR ranges allowed to use this key, for example `[\"203.0.113.0/24\"]`. Empty or `null` allows any IP.", "items": { "example": "203.0.113.0/24", "type": "string" }, "type": [ "array", "null" ] }, "name": { "description": "A human-readable name for the API key, such as 'Production API Key'.", "example": "Shine Time Booking (production)", "type": "string" }, "permissions": { "description": "The permissions policy for the API key: explicit permission statements, or a system role to inherit from. Statements without a `resources` array default to the owning account (Account API keys) or every key-addressable resource (App API keys).", "properties": { "statements": { "description": "Explicit permission statements. Required unless `system_role` is set.", "items": { "properties": { "actions": { "description": "Permission actions covered by this statement, for example `company:basic:read`.", "items": { "example": "company:basic:read", "type": "string" }, "type": "array" }, "grant": { "description": "Whether the actions are granted (`true`) or denied (`false`).", "example": true, "type": "boolean" }, "resources": { "description": "Resource identifiers the statement applies to, for example `biz_xxx` or `biz_xxx|pass_*`. Defaults to the key's owning resource when omitted.", "items": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "actions", "grant" ], "type": "object" }, "type": "array" }, "system_role": { "description": "A system role to inherit permissions from. Only Account API keys can use a system role.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", null ], "example": "admin", "type": [ "string", "null" ] } }, "type": "object" }, "resource_id": { "description": "The account (`biz_`) or app (`app_`) tag to create the API key for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "resource_type": { "description": "The type of resource that will own this API key.", "enum": [ "account", "app" ], "example": "account", "type": "string" } }, "required": [ "resource_id", "resource_type", "name", "permissions" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key 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 api-key management scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Create API Key", "tags": [ "API Keys" ] }, "x-whop-surface": "native" }, "/api_keys/permissions": { "get": { "description": "Lists the catalog of permission actions that can be granted to users, apps, and API keys — the source for the dashboard's permission pickers. Small and returned in full on one page.", "operationId": "listApiKeyPermissions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Permission" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "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": "permission catalog listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List the Permission Catalog", "tags": [ "API Keys" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/api_keys/{id}": { "delete": { "description": "Permanently revokes an API key; requests using its secret stop authenticating immediately. Default and agent-backend keys cannot be deleted.", "operationId": "deleteApiKey", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`: the key was revoked.", "example": true, "type": "boolean" }, "id": { "description": "The ID of the revoked key.", "example": "apik_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "api key deleted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the api key cannot be deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Delete API Key", "tags": [ "API Keys" ] }, "get": { "description": "Retrieves an API key with its effective permission grants. The full secret is never returned — rotate the key if it was lost.", "operationId": "retrieveApiKey", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key retrieved with grants but never the secret" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Retrieve API Key", "tags": [ "API Keys" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "API key ID, prefixed `apik_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an API key's name, permissions, API version, expiration, or IP allowlist. Fields that are omitted keep their current value; default keys cannot be modified.", "operationId": "updateApiKey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "Dated API version used when requests authenticated with this key omit the `Api-Version-Date` header. New keys default to the latest version.", "enum": [ "2025-01-01", "2026-06-08", "2026-06-09", "2026-06-20", "2026-07-01", "2026-07-08", "2026-07-08-1", "2026-07-18", "2026-07-20", "2026-07-22", "2026-07-23", "2026-07-25", "2026-07-26", "2026-07-27", "2026-07-29", "2026-07-29-1", "2026-07-31", "2026-08-03", "2026-08-05", "2026-08-05-1", "2026-08-10", "2026-08-12", "2026-08-13", "2026-08-14", "2026-08-21", "2026-08-21-1", "2026-08-25", "2026-08-25-1", "2026-08-25-2" ], "example": "2026-08-25-2", "type": "string" }, "expires_at": { "description": "When the API key should stop working, as an ISO 8601 timestamp. Omit (or pass `null` on update) for a key that never expires.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "ip_allowlist": { "description": "IPv4/IPv6 CIDR ranges allowed to use this key, for example `[\"203.0.113.0/24\"]`. Empty or `null` allows any IP.", "items": { "example": "203.0.113.0/24", "type": "string" }, "type": [ "array", "null" ] }, "name": { "description": "A new human-readable name for the API key.", "example": "Shine Time Booking (staging)", "type": [ "string", "null" ] }, "permissions": { "description": "The permissions policy for the API key: explicit permission statements, or a system role to inherit from. Statements without a `resources` array default to the owning account (Account API keys) or every key-addressable resource (App API keys).", "properties": { "statements": { "description": "Explicit permission statements. Required unless `system_role` is set.", "items": { "properties": { "actions": { "description": "Permission actions covered by this statement, for example `company:basic:read`.", "items": { "example": "company:basic:read", "type": "string" }, "type": "array" }, "grant": { "description": "Whether the actions are granted (`true`) or denied (`false`).", "example": true, "type": "boolean" }, "resources": { "description": "Resource identifiers the statement applies to, for example `biz_xxx` or `biz_xxx|pass_*`. Defaults to the key's owning resource when omitted.", "items": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "actions", "grant" ], "type": "object" }, "type": "array" }, "system_role": { "description": "A system role to inherit permissions from. Only Account API keys can use a system role.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", null ], "example": "admin", "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the api key cannot be modified" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Update API Key", "tags": [ "API Keys" ] }, "x-whop-surface": "native" }, "/api_keys/{id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "API key ID, prefixed `apik_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Rotates the API key's secret, invalidating the previous secret immediately. The response is the only place the new `secret_key` is returned.", "operationId": "rotateApiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key rotated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Rotate API Key", "tags": [ "API Keys" ] }, "x-whop-surface": "native" }, "/api_logs": { "get": { "description": "Lists the requests served by Whop's API with the account's API keys, newest first — every surface (GraphQL, REST, and native /api/v1), reads and failed requests included.", "operationId": "listApiLogs", "parameters": [ { "description": "The account (biz_*) whose API logs to list. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests served at or after this ISO 8601 timestamp. Defaults to 7 days before created_before, or 7 days ago.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests served before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests for this operation, matched exactly against the operation_name shown on each log row (for example api/v1/products#create).", "in": "query", "name": "operation_name", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests made with this HTTP method.", "in": "query", "name": "http_method", "required": false, "schema": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "type": "string" } }, { "description": "Only return requests that finished with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "success", "error" ], "type": "string" } }, { "description": "Only return requests made with this API key (apik_…).", "in": "query", "name": "api_key_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests that took at least this many milliseconds.", "in": "query", "name": "min_duration_ms", "required": false, "schema": { "type": "integer" } }, { "description": "Only return requests that took at most this many milliseconds.", "in": "query", "name": "max_duration_ms", "required": false, "schema": { "type": "integer" } }, { "description": "Number of logs to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 25, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "api_key_id": { "example": "apik_xxxxxxxxxxxxxx", "nullable": true, "type": "string" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "duration_ms": { "example": 12, "nullable": true, "type": "integer" }, "http_method": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", null ], "example": "POST", "nullable": true, "type": "string" }, "http_path": { "example": "/api/v1/products/prod_abc", "nullable": true, "type": "string" }, "id": { "example": "evt_xxxxxxxxxxxxxx_1", "type": "string" }, "ip_address": { "example": "87.106.27.99", "nullable": true, "type": "string" }, "operation_name": { "example": "api/v1/products#create", "nullable": true, "type": "string" }, "resource_id": { "example": "prod_abc", "nullable": true, "type": "string" }, "status": { "enum": [ "success", "error", null ], "example": "success", "nullable": true, "type": "string" }, "status_code": { "example": 200, "nullable": true, "type": "integer" }, "user_agent": { "example": "node", "nullable": true, "type": "string" } }, "required": [ "id", "created_at" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "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": "api logs listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks developer:logs:read on the account" }, "429": { "$ref": "#/components/responses/TooManyRequests", "description": "more than 10 reads per minute for the account" } }, "security": [ { "bearerAuth": [ "developer:logs:read" ] } ], "summary": "List Api Logs", "tags": [ "Api Logs" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/app_builds": { "get": { "description": "Returns a paginated list of build artifacts for an app, newest first, with optional platform, status, and creation-date filters.", "operationId": "listAppBuilds", "parameters": [ { "description": "The app to list builds for, prefixed `app_`.", "in": "query", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "description": "Filter builds by target platform.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "ios", "android", "web" ], "type": "string" } }, { "description": "Filter builds by review status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "pending", "approved", "rejected" ], "type": "string" } }, { "description": "Only return builds created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "Only return builds created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "The number of builds to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns builds after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of builds to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns builds before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AppBuild" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "app builds listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the app_id is missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "List App Builds", "tags": [ "App Builds" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Uploads a new build artifact for an app. Upload the file first (POST /files or a direct upload), then reference it here; iOS and Android take a .zip bundle, web takes a JavaScript file or a .zip archive of the hosted site.", "operationId": "createAppBuild", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ai_prompt_id": { "description": "The AI prompt that generated this build, if applicable.", "example": "prmt_xxxxxxxxxxxxxx", "type": "string" }, "app_id": { "description": "The app to create the build for, prefixed `app_`. Defaults to the app behind the presented credential.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "attachment": { "description": "The uploaded build file: `{ id }` for an existing file or `{ direct_upload_id }` for a completed direct upload.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "checksum": { "description": "A client-generated checksum of the build file, used to verify file integrity when unpacked.", "example": "xxxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The target platform for the build.", "enum": [ "ios", "android", "web" ], "example": "web", "type": "string" }, "source_attachment": { "description": "An optional compressed archive (.zip or .gz) of the source code that produced this build, stored alongside the build so it can be downloaded later. Referenced like `attachment`, and must be a different file.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "supported_app_view_types": { "description": "The view types this build supports. Only list the ones its code implements.", "items": { "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "example": "hub", "type": "string" }, "type": "array" } }, "required": [ "attachment", "checksum", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "app build 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 build-management scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Create App Build", "tags": [ "App Builds" ] }, "x-whop-surface": "native" }, "/app_builds/{id}": { "get": { "description": "Retrieves the details of an existing app build.", "operationId": "retrieveAppBuild", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "app build retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app build with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Retrieve App Build", "tags": [ "App Builds" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App build ID, prefixed `abld_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/app_builds/{id}/promote": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App build ID, prefixed `abld_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Promotes a draft or approved app build to production so it becomes the active version served to users. Draft builds enter review first.", "operationId": "promoteAppBuild", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "app build promotion started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the build cannot be promoted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app build with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Promote App Build", "tags": [ "App Builds" ] }, "x-whop-surface": "native" }, "/apps": { "get": { "description": "Lists apps on the Whop platform: the app store's live apps, or — with `account_id` and developer access to that account — every app the account owns. Requires authentication except for Whop's public app and website discovery lists. Public website discovery includes built official blueprints (verified apps with a product) and built, live community blueprints that Whop recommends.", "operationId": "listApps", "parameters": [ { "description": "Only return apps created by this account (`biz_` tag). With developer access to the account this includes its unlisted and hidden apps.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter apps by the type of end-user they are built for. Apps of type `website` are left out unless you ask for them by name.", "in": "query", "name": "app_type", "required": false, "schema": { "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "type": "string" } }, { "description": "Only return apps supporting this view type, such as `dashboard` or `hub`.", "in": "query", "name": "view_type", "required": false, "schema": { "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "type": "string" } }, { "description": "Only return apps whose Whop verification status matches this value. Omit this filter to include every verification status the caller can see.", "in": "query", "name": "verified", "required": false, "schema": { "type": "boolean" } }, { "deprecated": true, "description": "Legacy compatibility filter. Use `verified` for field equality. `true` returns verified apps; clients pinned before `2026-08-25-2` retain the earlier public website discovery behavior.", "in": "query", "name": "verified_apps_only", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return apps Whop recommends (or, with `false`, only those it does not), independently of verification status.", "in": "query", "name": "recommended", "required": false, "schema": { "type": "boolean" } }, { "description": "A search string matched against app names.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort apps by. Defaults to discoverable_at, showing the most recently published apps first. `template_usage` ranks Whop-verified apps first, then by how many businesses created apps from each app as a template.", "in": "query", "name": "order", "required": false, "schema": { "default": "discoverable_at", "enum": [ "created_at", "discoverable_at", "template_usage", "total_installs_last_30_days", "total_installs_last_7_days" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The number of apps to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns apps after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of apps to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns apps before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AppListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "apps listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Apps", "tags": [ "Apps" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Registers a new app on the Whop developer platform. Apps provide custom experiences that can be added to products.", "operationId": "createApp", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to create the app for (`biz_` tag). Defaults to the account behind the presented credential.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "app_type": { "default": "b2c_app", "description": "The type of app to create. Defaults to `b2c_app`.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "website", "type": "string" }, "base_url": { "description": "The base production URL where the app is hosted, such as `https://myapp.example.com`.", "example": "https://booking.shinetime.example", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for the app in PNG, JPEG, or GIF format, referencing an uploaded file: `{ id }` for an existing attachment or `{ direct_upload_id }` for a new direct upload.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "name": { "description": "The display name for the app, shown to users on the app store and product pages.", "example": "Shine Time Booking", "type": "string" }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs that users are redirected to after authorizing the app.", "items": { "example": "https://booking.shinetime.example/oauth/callback", "type": "string" }, "type": "array" }, "route": { "description": "The subdomain route where the app's hosted web builds are served, such as `myapp` for myapp.whop.site.", "example": "shine-time-booking-site", "type": [ "string", "null" ] } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "app 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 app-creation scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:create_app" ] } ], "summary": "Create App", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{app_id}/permissions": { "patch": { "description": "Updates the permission requirements for an app\n\nRequired permissions:\n - `developer:update_app_authorization`", "operationId": "updatePermissionsApp", "parameters": [ { "description": "The ID of the app the permission requirements are being updated for", "in": "path", "name": "app_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAppPermissionRequirements", "properties": { "requested_permissions": { "description": "The permissions that the app will request off of users when a user installs the app.", "items": { "description": "Input for creating a requested permission", "properties": { "action": { "description": "The action that the app will request off of users when a user installs the app.", "type": "string" }, "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" } }, "required": [ "action", "is_required", "justification" ], "type": "object" }, "type": "array" } }, "required": [ "requested_permissions" ], "type": "object" } } }, "required": true }, "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" }, "429": { "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": "Too many requests" }, "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_authorization" ] } ], "summary": "Update requested permissions", "tags": [ "Apps" ], "x-group-title": "Developer" } }, "/apps/{id}": { "delete": { "description": "Deletes an app. The app stops resolving within seconds — a website's site stops serving, and any claimed subdomain is reserved for a month before it can be claimed again.", "operationId": "deleteApp", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "app deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the app-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:update_app" ] } ], "summary": "Delete App", "tags": [ "Apps" ] }, "get": { "description": "Retrieves an app by ID, claimed route, or proxy domain id. Credential fields (api_key, default_api_key, secrets) render `null` unless the caller has the corresponding developer permission on the owning account.", "operationId": "retrieveApp", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "app retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "Retrieve App", "tags": [ "Apps" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App ID (prefixed `app_`), the app's claimed route, or its proxy domain id.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the settings, metadata, or status of an app. Fields that are omitted keep their current value.", "operationId": "updateApp", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "app_store_description": { "description": "The detailed description shown on the app store's in-depth app view page.", "example": "Shine Time Booking turns a whop into a booking calendar. Members pick a package, choose a slot that fits the day's route, and pay up front.", "type": "string" }, "app_type": { "description": "The type of end-user the app is built for. Cannot be changed on an app whose type is already `website`.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "b2c_app", "type": "string" }, "base_url": { "description": "The base production URL where the app is hosted. Set to `null` to take the app proxy offline.", "example": "https://booking.shinetime.example", "type": [ "string", "null" ] }, "dashboard_path": { "description": "The URL path for the account dashboard view.", "example": "/dashboard/[companyId]", "type": [ "string", "null" ] }, "description": { "description": "A short description of the app shown in listings and search results.", "example": "Let members book a mobile detailing appointment without leaving your whop.", "type": "string" }, "discover_path": { "description": "The URL path for the discover view.", "example": "/discover", "type": [ "string", "null" ] }, "experience_path": { "description": "The URL path for the member-facing hub view, such as `/experiences/[experienceId]`.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for the app in PNG, JPEG, or GIF format, referencing an uploaded file: `{ id }` for an existing attachment or `{ direct_upload_id }` for a new direct upload.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "name": { "description": "The display name for the app, shown to users on the app store and product pages.", "example": "Shine Time Booking Pro", "type": "string" }, "oauth_client_type": { "description": "How the app authenticates at the OAuth token endpoint.", "enum": [ "public", "confidential" ], "example": "confidential", "type": "string" }, "openapi_path": { "description": "The URL path to the app's OpenAPI spec file (requires the ai_chat capability).", "example": "/openapi.json", "type": [ "string", "null" ] }, "production_android_build_id": { "description": "The app build (`abld_` tag) to serve as the Android production build, or `null` to unassign it. Same rules as `production_web_build_id`.", "example": "apbu_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "production_ios_build_id": { "description": "The app build (`abld_` tag) to serve as the iOS production build, or `null` to unassign it. Same rules as `production_web_build_id`.", "example": "apbu_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "production_web_build_id": { "description": "The app build (`abld_` tag) to serve as the web production build, or `null` to unassign it. The build must belong to this app, target web, and be in the draft or approved status; a draft build is queued for approval and takes over once approved. Requires the `developer:manage_builds` scope.", "example": "apbu_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs users are redirected to after authorizing the app.", "items": { "example": "https://booking.shinetime.example/oauth/callback", "type": "string" }, "type": "array" }, "required_scopes": { "description": "The OAuth scopes the app requests from users when they install it.", "items": { "example": "read_user", "type": "string" }, "type": "array" }, "route": { "description": "The subdomain route where the app's hosted web builds are served.", "example": "shine-time-booking-pro", "type": "string" }, "secrets": { "description": "Secrets to add or overwrite on the app, as an object of string values. Keys not included are left untouched; pass null or an empty string as the value to delete a secret. Encrypted at rest and injected into the app's hosted server runtime.", "example": { "BOOKING_CALENDAR_ID": "cal_9f21" }, "type": "object" }, "skills_path": { "description": "The URL path to the app's skills directory (requires the ai_chat capability).", "example": "/skills", "type": [ "string", "null" ] }, "status": { "description": "Controls whether the app is published on Whop discovery or accessible only through its direct link. Publishing requires a name, icon, and description.", "enum": [ "live", "unlisted", "hidden" ], "example": "unlisted", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "app updated" }, "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 app-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:update_app" ] } ], "summary": "Update App", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{id}/deploy": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The app to deploy, prefixed `app_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Builds the app's current source and ships it. Returns the run it started, so the caller can render progress from this response and then follow it on the app's `deployment` field. Only one deployment runs per app at a time — calling this while one is in flight reports that run rather than starting a second, and calling it with nothing to publish reports that instead of starting one.", "operationId": "deployApp", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "draft": { "description": "Upload the build without making it live. Defaults to `false`, which deploys and promotes in one step.", "example": false, "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDeployment" } } }, "description": "deployment started" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Deploy App", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{id}/logs": { "get": { "description": "Lists a hosted app's server runtime logs, most recent first: console output, uncaught exceptions, and failed-request summaries captured on whop.site hosting. Logs are retained for 7 days.", "operationId": "listAppLogs", "parameters": [ { "description": "The ID of the app, which will look like app_*************.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Only return logs from this build.", "in": "query", "name": "app_build_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return console lines of this level.", "in": "query", "name": "level", "required": false, "schema": { "enum": [ "log", "debug", "info", "warn", "error" ], "type": "string" } }, { "description": "Only return logs whose message contains this text (case-insensitive).", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time window as an ISO 8601 timestamp. Defaults to 7 days before created_before.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of the time window as an ISO 8601 timestamp. Defaults to now.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The number of log lines to return (max 500).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching logs after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching logs before a later page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "app_build_id": { "example": "abld_123", "type": "string" }, "app_id": { "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "cpu_time_ms": { "example": 8, "type": "integer" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "level": { "enum": [ "log", "debug", "info", "warn", "error" ], "example": "error", "type": "string" }, "message": { "example": "TypeError: Cannot read properties of undefined (reading 'slotId')", "type": "string" }, "outcome": { "example": "exception", "type": [ "string", "null" ] }, "request_id": { "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "request_method": { "example": "GET", "type": [ "string", "null" ] }, "request_path": { "example": "/api/slots", "type": [ "string", "null" ] }, "response_status": { "example": 500, "type": [ "integer", "null" ] }, "source": { "enum": [ "console", "exception", "request" ], "example": "exception", "type": "string" }, "stack": { "example": "TypeError: Cannot read properties of undefined (reading 'slotId')\n at renderBookingSlot (/worker/booking.js:118:24)\n at handleRequest (/worker/index.js:42:11)", "type": [ "string", "null" ] }, "truncated": { "example": false, "type": "boolean" }, "wall_time_ms": { "example": 31, "type": "integer" } }, "required": [ "app_id", "app_build_id", "request_id", "created_at", "source", "level", "message" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "logs listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing the developer:logs:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "app not found" } }, "security": [ { "bearerAuth": [ "developer:logs:read" ] } ], "summary": "List App Logs", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{id}/permissions": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App ID, prefixed `app_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Replaces the set of permissions the app requests from users when they install it. Requires a user session: the `developer:update_app_authorization` scope cannot be delegated to API keys. Sensitive permissions require step-up verification.", "operationId": "updateAppPermissions", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "requested_permissions": { "description": "The full set of permissions the app requests on install; permissions not listed are removed.", "items": { "properties": { "action": { "description": "The permission action, for example `company:basic:read`.", "example": "company:basic:read", "type": "string" }, "is_required": { "description": "Whether installing the app requires granting this permission.", "example": true, "type": "boolean" }, "justification": { "description": "Why the app needs this permission (20-512 characters), shown to the installing user.", "example": "Reads basic account info to render the dashboard home.", "type": "string" } }, "required": [ "action", "is_required", "justification" ], "type": "object" }, "type": "array" } }, "required": [ "requested_permissions" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "requested permissions updated" }, "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 app-authorization scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:update_app_authorization" ] } ], "summary": "Update App Permissions", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/audiences": { "get": { "description": "Lists uploaded customer-list audiences for an account. Pass `audience_id` to return a specific audience.", "operationId": "listAudiences", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Audience ID, prefixed `adaud_`, used to filter the response to one audience.", "in": "query", "name": "audience_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by audience type: `custom` (uploaded lists) or `lookalike`.", "in": "query", "name": "audience_type", "required": false, "schema": { "enum": [ "custom", "lookalike" ], "type": "string" } }, { "description": "Filter by member source: `csv_upload` (uploaded lists) or `people_filter` (automatic audiences built from saved People filters).", "in": "query", "name": "source_type", "required": false, "schema": { "enum": [ "csv_upload", "people_filter" ], "type": "string" } }, { "description": "Number of audiences to return. Defaults to 20; maximum 100.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for the next page of audiences.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Audience" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Audiences listed." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." } }, "security": [ { "bearerAuth": [ "audience:basic:read" ] } ], "summary": "List Audiences", "tags": [ "Audiences" ] }, "post": { "description": "Creates an audience. Default (`audience_type` omitted or `custom`): creates one audience from an uploaded customer identity CSV file (`name`, `column_mapping`, and `file_id` required) and starts processing it; responds with the audience object. With `filters`: creates an audience from saved People filters (`name` required) — membership is built from the account's People data, and `auto_refresh` decides whether it keeps tracking the filters or keeps whoever matched at creation. With `audience_type: lookalike`: creates a ladder of Meta lookalike audiences from an existing ready custom audience (`source_audience_id`, `count`, and `percentage` required) — `count` equal similarity bands slicing the top `percentage`% (3 audiences at 6% = 0–2%, 2–4%, 4–6%), each returned as its own audience in a `{ data: [...] }` envelope.", "operationId": "createAudience", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "audience_type": { "description": "What to create. Defaults to `custom` (CSV upload).", "enum": [ "custom", "lookalike" ], "example": "lookalike", "type": "string" }, "auto_refresh": { "description": "Filter audiences only, and set only at creation. `true` (the default) rebuilds membership from the filters twice a day. `false` keeps whoever matched at creation and never rebuilds.", "example": true, "type": "boolean" }, "column_mapping": { "description": "Custom audiences only. Maps supported identity fields to CSV column headers. Map at least one of `email` or `phone`.", "properties": { "country": { "description": "CSV header for ISO 3166-1 alpha-2 country codes, such as `US`.", "example": "Country", "type": "string" }, "email": { "description": "CSV header for email addresses.", "example": "Email", "type": "string" }, "first_name": { "description": "CSV header for first names.", "example": "First Name", "type": "string" }, "last_name": { "description": "CSV header for last names.", "example": "Last Name", "type": "string" }, "ltv": { "description": "CSV header for each customer's lifetime value — a non-negative number, currency symbols allowed. When mapped, Meta creates the audience as value-based, so lookalikes built from it favor people similar to the highest-value customers.", "example": "Lifetime Value", "type": "string" }, "phone": { "description": "CSV header for phone numbers.", "example": "Phone", "type": "string" } }, "type": "object" }, "count": { "description": "Lookalikes only. Number of lookalike audiences to create (1–6).", "example": 3, "type": "integer" }, "file_id": { "description": "Custom audiences only. The uploaded customer CSV — a file id (`file_...`) returned by `POST /files`.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "filters": { "description": "Filter audiences only. The People filters that define membership, keyed exactly as `GET /people` accepts them — for example `{\"os\": \"iOS\", \"country\": \"US\"}`. Date filters must be rolling windows — `first_seen_within_days` or `last_seen_within_days` — so the audience re-anchors on every refresh; fixed dates such as `first_seen_after` are rejected. Source values are canonical source paths (`whop:::`, `ext::...`, `referrer:`, `direct`), exact or with a trailing `:*` wildcard.", "example": { "country": "US", "last_seen_within_days": 30 }, "type": "object" }, "name": { "description": "Audience display name. Required for custom audiences; lookalike names are generated from the source audience.", "example": "Austin visitors, last 30 days", "type": "string" }, "percentage": { "description": "Lookalikes only. Total similarity reach as a whole percent (1–20), sliced evenly across `count` — must be divisible by `count`.", "example": 6, "type": "integer" }, "source_audience_id": { "description": "Lookalikes only. The ready custom audience (`adaud_`) to build from; it needs at least 100 matched people.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Audience" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/Audience" }, "type": "array" } }, "required": [ "data" ], "type": "object" } ] } } }, "description": "Audience created — the audience object for custom audiences, or `{ data: [...] }` for lookalike ladders." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Create Audience", "tags": [ "Audiences" ] }, "x-whop-surface": "native" }, "/audiences/{id}": { "delete": { "description": "Deletes an audience so it is no longer available for targeting.", "operationId": "deleteAudience", "parameters": [ { "description": "Audience ID, prefixed `adaud_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Audience deleted." } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Delete Audience", "tags": [ "Audiences" ] }, "patch": { "description": "Renames an audience. For an audience built from People filters that keeps itself up to date, pass `filters` to replace them, which rebuilds membership immediately. Whether an audience auto refreshes is set when it is created.", "operationId": "updateAudience", "parameters": [ { "description": "Audience ID, prefixed `adaud_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "filters": { "description": "Replaces the People filters that define membership. The whole definition is replaced rather than merged, so send every filter you want to keep — a filter you leave out stops applying. Keys and values are the ones `GET /people` accepts, such as an `os` of `iOS` or a `country` of `US`, and at least one filter is required. Date filters must be rolling windows — `first_seen_within_days` or `last_seen_within_days` — so the audience re-anchors every time it rebuilds; fixed dates such as `first_seen_after` are rejected, as is `audience_id`. An array value holds at most 500 items, and each value at most 10 KB. Only an audience with a `source_type` of `people_filter` and `auto_refresh` of `true` accepts filters: an uploaded list has no filters to replace, and with auto refresh off the audience keeps the people it matched when it was built, so create a new audience instead.", "example": { "country": "US", "last_seen_within_days": 60 }, "type": "object" }, "name": { "description": "New audience display name. A blank value is ignored rather than clearing the name.", "example": "Austin visitors, last 60 days", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } }, "description": "Audience updated." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Update Audience", "tags": [ "Audiences" ] }, "x-whop-surface": "native" }, "/audiences/{id}/add_people": { "post": { "description": "Adds users from a new CSV file to an existing uploaded custom audience. The file uses the audience's saved column mapping, processing happens in the background, and existing audience members remain unchanged.", "operationId": "addAudiencePeople", "parameters": [ { "description": "Audience ID, prefixed `adaud_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "file_id": { "description": "The new customer CSV — a file id (`file_...`) returned by `POST /files`. Its headers must match the audience's saved column mapping.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "file_id" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } }, "description": "Audience upload accepted." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Add People", "tags": [ "Audiences" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "role", "required": false, "schema": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "Filter authorized users by their assigned role within the company." }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "elevation": { "description": "Re-authentication proof required to perform this sensitive action.", "properties": { "authenticator_data": { "description": "The WebAuthn authenticator data (base64).", "type": [ "string", "null" ] }, "client_data_json": { "description": "The WebAuthn client data JSON (base64).", "type": [ "string", "null" ] }, "credential_id": { "description": "The WebAuthn credential ID (base64).", "type": [ "string", "null" ] }, "email_code": { "description": "The 6-digit code emailed to the user.", "type": [ "string", "null" ] }, "signature": { "description": "The WebAuthn signature (base64).", "type": [ "string", "null" ] }, "totp_code": { "description": "The 6-digit code from the authenticator app or SMS.", "type": [ "string", "null" ] }, "use_finance_session": { "description": "Reuse an existing elevated session (for SMS/email 2FA users).", "type": [ "boolean", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "role": { "$ref": "#/components/schemas/GrantableAuthorizedUserRoles", "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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": "Lists bounties visible to the credential — for an account API key, the account's bounties including scheduled drafts; for a user token, the bounties the user can see and work.", "operationId": "listBounties", "parameters": [ { "description": "Scope the list to this account (`biz_` tag). Requires read access to the account; account API keys may pass their own account or a connected account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "List the bounties this user participated in (`user_` tag). Must be the authenticated user.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "scheduled", "open", "closed", "completed", "canceled" ], "type": "string" } }, { "description": "Filter by the poster's declared goal. Bounties created before the goal taxonomy carry no goal and never match this filter.", "in": "query", "name": "business_goal_type", "required": false, "schema": { "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "type": "string" } }, { "description": "Only bounties workable from this country, as an ISO 3166-1 alpha-2 code. Bounties with no country targeting are workable worldwide and always match.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Only bounties posted to this forum experience, prefixed `exp_`. An unknown experience, or one outside the caller's scope, matches nothing.", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Substring match on the bounty title or ID.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only bounties created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only bounties created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "gross_paid_out_amount", "gross_reward_amount" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of bounties to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of bounties to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BountyListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "bounties listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the bounty-read scope" } }, "security": [ { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "List Bounties", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a bounty and escrows its reward pool. Publishes immediately, or as a scheduled draft when you set `publish_at`.", "operationId": "createBounty", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "accepted_submissions_limit": { "description": "Number of submissions that can be accepted (winner slots). Defaults to 1. The escrowed total is `gross_reward_amount` times this limit and must be at least $5.", "example": 3, "type": [ "integer", "null" ] }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`.", "example": 2, "minimum": 1, "type": [ "integer", "null" ] }, "account_id": { "description": "Account whose balance funds the bounty pool (`biz_` tag). Defaults to the caller's personal balance. Requires permission to move the account's funds.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "allowed_country_codes": { "description": "Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "items": { "example": "US", "type": "string" }, "type": [ "array", "null" ] }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once here.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "example": "clipping", "type": "string" }, "capture_spec": { "description": "Per-bounty overrides of the served capture contract. Only accepted when `business_goal_type` is `data_capture`; omitted fields keep the platform defaults, and the resulting contract is echoed back as `capture_spec` on the bounty.", "properties": { "bitrate_target_mbps": { "description": "Average bitrate the recorder encodes at, in megabits per second. Must sit within the served floor and ceiling.", "example": 12, "type": "integer" }, "embed_camera_metadata": { "description": "Whether the recorder also writes camera make and model into the video container's metadata.", "example": true, "type": "boolean" }, "frame_gap_tolerance_ms": { "description": "Longest stall between consecutive frames a clip may contain before the client rejects it, in milliseconds. Unlike the recording fields this one can also be tuned after the bounty is created, since it bounds what is accepted rather than how footage is captured.", "example": 2000, "type": "integer" }, "min_clip_duration_seconds": { "description": "Minimum length of a single clip, in seconds.", "example": 120, "type": "integer" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate across all its clips before it can be submitted, in seconds. Must be a whole number of hours between 1 and 12. Editable after create, until someone starts an attempt.", "example": 14400, "type": "integer" }, "stabilization_mode": { "description": "How the recorder configures video stabilization. `off` preserves raw motion for pose extraction.", "enum": [ "off", "on", "any" ], "example": "off", "type": "string" } }, "type": "object" }, "description": { "description": "Full task instructions shown to workers.", "example": "Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.", "type": "string" }, "experience_id": { "description": "Experience to host the bounty in (`exp_` tag). Any visibility — public for an open bounty, private for an invited one. Required unless account_id is set, in which case the bounty anchors in that account's public forum.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "frequency": { "description": "How often the schedule creates a new bounty. Each occurrence is a separate bounty. Defaults to `once`; only applies with `publish_at`.", "enum": [ "once", "hourly", "daily", "weekly", "monthly" ], "example": "weekly", "type": "string" }, "gross_reward_amount": { "description": "Gross bounty-pool amount (USD) escrowed per accepted submission, in whole dollars. Platform fees and affiliate shares are paid from this amount.", "example": 40.0, "type": "number" }, "publish_at": { "description": "ISO 8601 time to publish the bounty. When set, the bounty is created as a hidden draft and funded + published at this time instead of immediately.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "publish_at_timezone": { "description": "IANA timezone for recurring occurrences. Required when publish_at is set.", "example": "America/Chicago", "type": [ "string", "null" ] }, "title": { "description": "Short name of the task shown to workers.", "example": "Record interior detailing passes", "type": "string" } }, "required": [ "title", "description", "gross_reward_amount" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "bounty created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing reward amount" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential cannot fund the requested account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "bounty:create" ] }, { "bearerAuth": [ "payout:transfer_funds" ] } ], "summary": "Create Bounty", "tags": [ "Bounties" ] }, "x-whop-surface": "native" }, "/bounties/{bounty_id}/submissions": { "get": { "description": "Lists a bounty's publicly visible work — submitted, approved, and denied submissions in the reduced public shape. Authentication is optional; a bounty that is not publicly visible returns `404`.", "operationId": "listPublicBountySubmissions", "parameters": [ { "description": "The bounty whose public submissions to list (`bnty_` tag).", "in": "path", "name": "bounty_id", "required": true, "schema": { "type": "string" } }, { "description": "Filter by lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "submitted", "approved", "denied" ], "type": "string" } }, { "description": "Only submissions created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only submissions created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "updated_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of submissions to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of submissions to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PublicBountySubmission" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "public bounty submissions listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty not found or not publicly visible" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "List Public Submissions", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/bounties/{bounty_id}/submissions/{id}": { "get": { "description": "Retrieves one of a bounty's publicly visible submissions in the reduced public shape — the read behind a shared proof link, whose submission is usually outside the bounty page's capped preview. Authentication is optional; a bounty that is not publicly visible, and a submission that is not publicly visible work on it, both return `404`.", "operationId": "retrievePublicBountySubmission", "parameters": [ { "description": "The bounty the submission belongs to (`bnty_` tag).", "in": "path", "name": "bounty_id", "required": true, "schema": { "type": "string" } }, { "description": "The submission to retrieve (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBountySubmission" } } }, "description": "public bounty submission returned" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not found or not publicly visible" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "Retrieve Public Submission", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/bounties/{id}": { "get": { "description": "Retrieves a bounty by ID. Authentication is optional: a request with no credential reads the bounty when it is publicly visible — published or completed, and not restricted to a private experience's members. Bounties outside the caller's scope, and bounties not publicly visible to an anonymous caller, return `404`.", "operationId": "retrieveBounty", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "bounty retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty not visible to the caller" } }, "security": [ {}, { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "Retrieve Bounty", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Bounty ID (`bnty_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a bounty. A published bounty accepts title, description, and country targeting while it is still open with nothing under review. A scheduled (not-yet-published) draft additionally accepts the reward, winner slots, and schedule.", "operationId": "updateBounty", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "accepted_submissions_limit": { "description": "Scheduled drafts only. Number of submissions that can be accepted (winner slots).", "example": 3, "type": [ "integer", "null" ] }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`. Editable while the bounty is still open with nothing under review.", "example": 2, "minimum": 1, "type": [ "integer", "null" ] }, "allowed_country_codes": { "description": "Replace the countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "items": { "example": "US", "type": "string" }, "type": [ "array", "null" ] }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once here.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "example": "data_capture", "type": "string" }, "description": { "description": "New full task instructions.", "example": "Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.", "type": "string" }, "frequency": { "description": "Scheduled drafts only. How often the schedule creates a new bounty.", "enum": [ "once", "hourly", "daily", "weekly", "monthly" ], "example": "weekly", "type": "string" }, "gross_reward_amount": { "description": "Scheduled drafts only. Gross bounty-pool amount (USD) escrowed per accepted submission. The escrowed total (this times accepted_submissions_limit) must stay at least $5.", "example": 40.0, "type": [ "number", "null" ] }, "publish_at": { "description": "Scheduled drafts only. New ISO 8601 time to publish the draft. Must be in the future.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "publish_at_timezone": { "description": "Scheduled drafts only. IANA timezone for recurring occurrences.", "example": "America/Chicago", "type": [ "string", "null" ] }, "title": { "description": "New short name of the task.", "example": "Record interior detailing passes", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "bounty updated" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty the caller cannot manage" } }, "security": [ { "bearerAuth": [ "bounty:update" ] } ], "summary": "Update Bounty", "tags": [ "Bounties" ] }, "x-whop-surface": "native" }, "/bounties/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Bounty ID (`bnty_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a bounty. With no in-flight work, it cancels immediately and refunds the funder. Otherwise it stops new submissions and cancels once the in-flight work resolves and pays out. Repeating the request is a no-op. A bounty that already paid out every slot returns `400`.", "operationId": "cancelBounty", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "cancellation requested" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "bounty already completed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks fund authority on the funding account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty outside the caller's scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "bounty:basic:read", "payout:transfer_funds" ] } ], "summary": "Cancel", "tags": [ "Bounties" ] }, "x-whop-surface": "native" }, "/bounty_submissions": { "get": { "description": "Lists bounty submissions visible to the credential — for a user token, the submissions they authored plus those on bounties they posted; for an account API key, the submissions on the account's bounties. For the anonymous view of one bounty's reviewed work, use the submissions list under the bounty instead.", "operationId": "listBountySubmissions", "parameters": [ { "description": "Scope the list to submissions on this account's bounties (`biz_` tag). Requires read access to the account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only submissions on this bounty (`bnty_` tag).", "in": "query", "name": "bounty_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "in_progress", "submitted", "approved", "denied" ], "type": "string" } }, { "description": "Only submissions created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only submissions created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "updated_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of submissions to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of submissions to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BountySubmission" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "bounty submissions listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the bounty-read scope" } }, "security": [ { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "List Bounty Submissions", "tags": [ "Bounty Submissions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a submission on a workforce bounty. Include a `deliverable` payload — any combination of links and uploaded files, with at least one of the two — and the submission goes straight to review; create is the only step. For `data_capture` bounties, omit the deliverable: this starts a claimed attempt whose proof accumulates server-side, and the separate submit endpoint sends it to review once complete. Requires a user credential — account API keys cannot author submissions.", "operationId": "createBountySubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "affiliate_code": { "description": "Affiliate code crediting the referrer, when the worker arrived through one.", "example": "tanyacole", "type": [ "string", "null" ] }, "bounty_id": { "description": "The bounty to submit to (`bnty_` tag).", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "deliverable": { "description": "The submitted work. Combine `urls`, `file_ids`, and `caption` freely; at least one link or file is required.", "properties": { "caption": { "description": "Written context shown to reviewers alongside the work.", "example": "Ceramic coating reveal, shot at the Burnet Rd bay", "type": [ "string", "null" ] }, "file_ids": { "description": "IDs of uploaded files attached as work, up to 10, each prefixed `file_`. Combinable with `urls` and `caption`.", "items": { "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "type": { "description": "Legacy shape selector; no longer selects anything. When present it must name an inline shape (`content_url` or `media`).", "enum": [ "content_url", "media", null ], "example": "content_url", "type": [ "string", "null" ] }, "urls": { "description": "Links to the posted work, up to 10. Combinable with `file_ids` and `caption`.", "items": { "example": "https://youtube.com/shorts/2", "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] }, "metadata": { "description": "Optional capture metadata describing where and how the footage was recorded. Persisted on the submission. On a `data_capture` bounty every field except `fov` is required whenever metadata is provided.", "properties": { "city": { "description": "City the footage was recorded in.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Country the footage was recorded in.", "example": "US", "type": [ "string", "null" ] }, "device": { "description": "Device the footage was recorded on.", "example": "iPhone 15 Pro", "type": [ "string", "null" ] }, "fov": { "description": "Horizontal field of view in degrees.", "example": 120, "type": [ "integer", "null" ] }, "operator": { "description": "Identifier of the person who recorded the footage.", "example": "mwebb", "type": [ "string", "null" ] }, "site": { "description": "Site or venue the footage was recorded at.", "example": "BurnetRd", "type": [ "string", "null" ] }, "station": { "description": "Station or position within the site.", "example": "Bay2", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "required": [ "bounty_id" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BountySubmission" } } }, "description": "submission created with an inline deliverable" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "deliverable type must name an inline shape" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "user credential lacks the submission-create scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "bounty:submission:create" ] } ], "summary": "Create Bounty Submission", "tags": [ "Bounty Submissions" ] }, "x-whop-surface": "native" }, "/bounty_submissions/{id}": { "delete": { "description": "Cancels the caller's own active attempt on a bounty and discards any accumulated capture clips. Only the worker who started the attempt can cancel it — account API keys cannot.", "operationId": "cancelBountySubmission", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the cancelled submission.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "attempt cancelled" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "only the submission's own worker can cancel it" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not found" } }, "security": [ { "bearerAuth": [ "bounty:submission:delete" ] } ], "summary": "Cancel Bounty Submission", "tags": [ "Bounty Submissions" ] }, "get": { "description": "Retrieves one bounty submission the credential can see — one the caller authored, or one on a bounty they posted or their account owns. Reading another member's work on an account's bounty takes `account_id`, the same way the list does.", "operationId": "retrieveBountySubmission", "parameters": [ { "description": "Read the submission as this account (`biz_` tag), scoping the lookup to its bounties rather than the caller's own work. Requires read access to the account. Without it the lookup covers only what the credential owns — the submissions the caller authored plus those on bounties they posted.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BountySubmission" } } }, "description": "bounty submission returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not visible to the credential" } }, "security": [ { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "Retrieve Bounty Submission", "tags": [ "Bounty Submissions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The bounty submission to act on (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/bounty_submissions/{id}/submit": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The claimed attempt to submit for review (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Submits a claimed attempt for review. A livestream attempt needs an ended proof stream and can attach an optional `deliverable` — links, files, and a caption in any combination; if the attempt already went to review when its stream ended, the payload attaches to it once, until reviewers start voting. A data capture attempt instead needs enough validated clip time and takes no payload. Only the worker who started the attempt can submit it — account API keys cannot.", "operationId": "submitBountySubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "deliverable": { "description": "Work to attach to the submission. Combine `urls`, `file_ids`, and `caption` freely; all are optional.", "properties": { "caption": { "description": "Written context shown to reviewers alongside the work.", "example": "Full interior detail, start to finish, on a 2019 Tacoma.", "type": [ "string", "null" ] }, "file_ids": { "description": "IDs of uploaded files attached as work, up to 10, each prefixed `file_`. Combinable with `urls` and `caption`.", "items": { "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "urls": { "description": "Links to the posted work, up to 10. Combinable with `file_ids` and `caption`.", "items": { "example": "https://youtube.com/shorts/4", "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BountySubmission" } } }, "description": "attempt submitted for review" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the attempt has not accumulated enough proof to submit" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "only the attempt's own worker can submit it" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the submission's evidence is already frozen" } }, "security": [ { "bearerAuth": [ "bounty:submission:create" ] } ], "summary": "Submit Bounty Submission", "tags": [ "Bounty Submissions" ] }, "x-whop-surface": "native" }, "/card_transactions": { "get": { "description": "Lists an account's card transactions, newest first. Defaults to the account the credential belongs to. Covers every card the owner has ever had, including canceled cards and spend that predates a re-application, and team members only see transactions on the cards assigned to them. Pass `transaction_ids` to fetch specific transactions instead of paging for them.", "operationId": "listCardTransactions", "parameters": [ { "description": "The account whose card transactions to list, prefixed `biz_`. Defaults to the credential's account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Return only these card transactions, each prefixed `citx_`. Repeat the parameter, or pass one comma-separated value.", "in": "query", "name": "transaction_ids", "required": false, "schema": { "items": { "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Return only transactions charged to these cards, each prefixed `icrd_`.", "in": "query", "name": "card_id", "required": false, "schema": { "items": { "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Return only transactions on cards assigned to these users, each prefixed `user_`.", "in": "query", "name": "cardholder_id", "required": false, "schema": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Return only transactions with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "completed", "reversed", "declined" ], "type": "string" } }, { "description": "Return only transactions authorized at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Return only transactions authorized at or before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to `created_at`.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The number of card transactions to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns card transactions after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of card transactions to return, counting back from the end.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns card transactions before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CardTransaction" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "no owner passed falls back to the credential's account" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "transaction_ids is not a card transaction id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List Card Transactions", "tags": [ "Cards" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/card_transactions/{id}": { "get": { "description": "Fetches a single card transaction by its `citx_` identifier. The owner defaults to the account the credential belongs to.", "operationId": "retrieveCardTransaction", "parameters": [ { "description": "The account that owns the transaction, prefixed `biz_`. Defaults to the credential's account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTransaction" } } }, "description": "card transaction found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "card transaction belongs to another owner" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve Card Transaction", "tags": [ "Cards" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The card transaction ID, prefixed `citx_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/cards": { "get": { "description": "Lists the Whop cards of an account or user, including ones still being set up. Team members only see the cards assigned to them.", "operationId": "listCards", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2029", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "8319", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailing supplies", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 0, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "invited", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "cards listed for an assigned cardholder without the ledger scope" }, "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 payout-account-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that owner is visible to the credential" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List Cards", "tags": [ "Cards" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Issue a virtual card, or apply for card issuing. An account with no application files one here and gets back a `202`; call again to issue the card once it is approved.", "operationId": "createCard", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "assigned_user_id": { "description": "The account member (a user_ identifier) to assign the card to. Required for business card issuing accounts, and whenever a company API key files an account's first card application.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "A display name for the card.", "example": "Detailer card", "type": "string" }, "spend_limit": { "description": "Spending limit amount, in dollars.", "example": 500, "type": "number" }, "spend_limit_frequency": { "description": "The window the spend limit applies to.", "enum": [ "daily", "weekly", "monthly", "one_time" ], "example": "weekly", "type": "string" }, "transaction_limit": { "description": "Per-transaction limit amount, in dollars.", "example": 200, "type": "number" }, "user_id": { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2030", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 2500.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "monthly", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailing supplies", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 0, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" } } }, "description": "card created" }, "202": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "object": { "enum": [ "card_provisioning" ], "example": "card_provisioning", "type": "string" }, "provisioning_job_id": { "description": "Background job ID to poll until the card is ready.", "example": "card-issuing-create-card-123", "type": "string" } }, "required": [ "object", "provisioning_job_id" ], "type": "object" }, { "properties": { "invitation_sent": { "description": "Always true; the member must finish onboarding before the card is issued.", "example": true, "type": "boolean" }, "object": { "enum": [ "card_invitation" ], "example": "card_invitation", "type": "string" } }, "required": [ "object", "invitation_sent" ], "type": "object" }, { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" } ] } } }, "description": "card not issued synchronously: application submitted, provisioning started, or onboarding invitation sent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the card or its application cannot be created as requested" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout-account-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that owner is visible to the credential" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the account's card application is not approved" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Create Card", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "/cards/{id}": { "get": { "description": "Retrieve a single card.", "operationId": "retrieveCard", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" } } }, "description": "card retrieved with its PIN by the assigned cardholder" }, "404": { "$ref": "#/components/responses/NotFound", "description": "card not found" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve Card", "tags": [ "Cards" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Card ID to retrieve, prefixed `icrd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Update, freeze, or cancel a card. Updating the card's name, billing address, or limits requires both `payout:account:update` and `company:balance:read`; a card's assigned holder may update their own card's pin and frozen state with any user token.", "operationId": "updateCard", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "billing": { "description": "New billing address. Requires line1, city, region, postal_code, and country_code. On an invited card, passing billing alone (as the invited user) completes onboarding and starts card provisioning.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": "string" }, "country_code": { "description": "Billing country code, ISO 3166-1 alpha-2.", "example": "US", "type": "string" }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": "string" }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": "string" }, "region": { "description": "Billing region or state.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "region", "postal_code", "country_code" ], "type": "object" }, "canceled": { "description": "Pass `true` to permanently cancel the card. A canceled card cannot be uncanceled. Cannot be combined with other fields.", "example": true, "type": "boolean" }, "frozen": { "description": "Pass `true` to freeze the card, `false` to unfreeze it. The assigned cardholder may freeze their own card without the payout:account:update scope.", "example": true, "type": "boolean" }, "name": { "description": "A display name for the card.", "example": "Detailing supplies", "type": "string" }, "pin": { "description": "New 4-digit PIN. Can only be set on a card assigned to the acting user, who may set it without the payout:account:update scope.", "example": "1234", "type": "string" }, "remove_limit": { "description": "Pass `true` to remove the spending limit (make the card unlimited).", "example": true, "type": "boolean" }, "spend_limit": { "description": "Spending limit amount, in dollars.", "example": 2500.0, "type": "number" }, "spend_limit_frequency": { "description": "The window the spend limit applies to.", "enum": [ "daily", "weekly", "monthly", "one_time" ], "example": "monthly", "type": "string" }, "transaction_limit": { "description": "Per-transaction limit amount, in dollars.", "example": 500.0, "type": "number" }, "user_id": { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailing supplies", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" } } }, "description": "invited card onboarding completed: card provisioning started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid update request" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout-account-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "card not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the issuer declined the cardholder this card was invited for" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] }, { "bearerAuth": [] } ], "summary": "Update Card", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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": "Lists checkout configurations for an account.", "operationId": "listCheckoutConfigurations", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Only return checkout configurations for this plan ID, prefixed `plan_`.", "in": "query", "name": "plan_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return checkout configurations created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return checkout configurations created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Field used to sort checkout configurations.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of checkout configurations to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for the next page of results.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "example": "tanyacole", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the plan's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "properties": { "disabled": { "description": "Payment methods explicitly disabled.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "id": { "description": "Checkout configuration ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the plan or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "example": true, "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 0.0, "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59.0, "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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": "Checkout URL you can send to customers.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "checkout configurations listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "checkout_configuration:basic:read" ] } ], "summary": "List checkout configurations", "tags": [ "Checkout Configurations" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a reusable checkout configuration for an existing or inline plan.", "operationId": "createCheckoutConfiguration", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "plan_id": "plan_xxxxxxxxxxxxx" }, "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code to apply to the checkout.", "example": "tanyacole", "type": [ "string", "null" ] }, "currency": { "description": "Currency used for setup-mode payment method availability.", "example": "usd", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later. Defaults to `payment`.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` uses the plan or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan": { "description": "Plan attributes used to create or find a plan for this checkout configuration. Mutually exclusive with `plan_id`.", "properties": { "account_id": { "description": "Account ID for the inline plan, prefixed `biz_`. Defaults to the account resolved from the request.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": [ "string", "null" ] }, "description": { "description": "Customer-visible plan description.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Whether to create a new plan instead of reusing a matching one.", "example": true, "type": [ "boolean", "null" ] }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 249, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value metadata stored on the plan.", "example": { "bay": "2" }, "type": [ "object", "null" ] }, "override_tax_type": { "description": "Tax classification override for this plan.", "example": "inclusive", "type": [ "string", "null" ] }, "payment_method_configuration": { "description": "Payment method overrides for the inline plan. `null` uses platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for this plan.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for this plan.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time", null ], "example": "one_time", "type": [ "string", "null" ] }, "product_id": { "description": "Product ID the inline plan should belong to, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist", null ], "example": "buy_now", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase.", "example": 25, "type": [ "integer", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for the inline plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "Plan display name shown to customers.", "example": "Ceramic Coating — Full Vehicle", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link", null ], "example": "visible", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "plan_id": { "description": "Existing plan ID, prefixed `plan_`. Mutually exclusive with `plan`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this checkout.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "example": "tanyacole", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the plan's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "properties": { "disabled": { "description": "Payment methods explicitly disabled.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "id": { "description": "Checkout configuration ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "setup", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the plan or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "example": true, "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 0.0, "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59.0, "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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": "Checkout URL you can send to customers.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" } } }, "description": "checkout configuration created for an existing plan" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "checkout_configuration:create" ] } ], "summary": "Create a checkout configuration", "tags": [ "Checkout Configurations" ] }, "x-whop-surface": "native" }, "/checkout_configurations/{id}": { "delete": { "description": "Deletes a checkout configuration so its checkout URL can no longer be used.", "operationId": "deleteCheckoutConfiguration", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted checkout configuration.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "checkout configuration deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" } }, "security": [ { "bearerAuth": [ "checkout_configuration:delete" ] } ], "summary": "Delete a checkout configuration", "tags": [ "Checkout Configurations" ] }, "get": { "description": "Retrieves a checkout configuration by ID. This endpoint is public so a checkout page can load from the configuration URL.", "operationId": "retrieveCheckoutConfiguration", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "example": "tanyacole", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the plan's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "properties": { "disabled": { "description": "Payment methods explicitly disabled.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "id": { "description": "Checkout configuration ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the plan or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "example": true, "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 0.0, "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59.0, "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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": "Checkout URL you can send to customers.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" } } }, "description": "checkout configuration found (unauthenticated)" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" } }, "security": [ {}, { "bearerAuth": [ "checkout_configuration:basic:read" ] } ], "summary": "Retrieve a checkout configuration", "tags": [ "Checkout Configurations" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the checkout configuration.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for results. Defaults to descending." }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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": { "country": { "description": "The country the company is located in. Defaults to the parent company's country for connected accounts, or the owner's IP-derived country.", "oneOf": [ { "$ref": "#/components/schemas/Countries" }, { "type": "null" } ] }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "transaction_type", "required": false, "schema": { "$ref": "#/components/schemas/CompanyTokenTransactionTypes", "description": "Filter transactions by type." }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/confirmation_tokens": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Mints a single-use, short-lived confirmation token from what the buyer entered on your collection surface: the payment method payload, billing details, and attested save consent. Public and rate-limited — the account_id in the body scopes the token but does not authenticate. Confirm it with POST /payments from your server.", "operationId": "createConfirmationToken", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "billing_details": { "address": { "city": "Austin", "country": "US", "line1": "123 Main St", "postal_code": "78701" }, "email": "buyer@example.com", "name": "Buyer Name" }, "payment_method": { "card": { "brand": "visa", "last4": "4242", "token_intent": "bt_ti_123" }, "category": "card", "type": "card" }, "setup_future_usage": "off_session" }, "properties": { "account_id": { "description": "The account (biz_) this token is scoped to — the publishable identity.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "billing_details": { "description": "Billing details collected with the method. `email` is always required; cards additionally require `name` and an address with `line1` and `country`.", "properties": { "address": { "example": { "city": "Austin", "country": "US", "line1": "123 Main St", "postal_code": "78701" }, "type": [ "object", "null" ] }, "email": { "example": "marcus@shinetime.example", "type": "string" }, "name": { "example": "Buyer Name", "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "browser_info": { "description": "Screen/runtime facts from the buyer's browser (platform, screen dimensions, language, ...) used for authentication ceremonies. Header-derived fields are captured server-side.", "example": { "browser_time_difference": 0, "java_enabled": false, "javascript_enabled": false, "language": "de-DE" }, "type": [ "object", "null" ] }, "payment_method": { "description": "The collected method: `type` names the payment method, `category` names the payload shape, and the category-keyed object carries the payload. Wallets are the exception: their payload rides the type key (`apple_pay` / `google_pay`). Send exactly the one payload arm the category selects — extra arms are rejected. Redirect-flow methods (category `redirect`, `bank_transfer`, `voucher`, and redirect wallets like `cashapp`) collect nothing and send no payload arm.", "properties": { "apple_pay": { "description": "Type `apple_pay` (category `wallet`) only.", "properties": { "merchant_identifier": { "description": "The merchant identifier the Apple Pay sheet validated with — the same hostname-matched value from the type's `merchants` list the session ceremony used. Apple encrypts the wallet token for the certificate attached to this exact identifier, so the charge needs it to decrypt. Omit it when the ceremony omitted it; must be one the account has registered.", "example": "merchant.whop.com.y.uno", "type": [ "string", "null" ] }, "token_intent": { "description": "The Basis Theory token intent the Apple Pay sheet flow vaulted the raw wallet token into.", "example": "bt_ti_apple_789", "type": "string" } }, "required": [ "token_intent" ], "type": "object" }, "balance": { "description": "Category `balance` only. Names one of the buyer's spendable platform balances. Requires a buyer credential — whether the caller may spend the wallet is checked against their own grants, so another user's id reads as not found.", "properties": { "id": { "description": "The balance to spend — a balance id (ldgr_) from GET /balances.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "bank_debit": { "description": "Category `bank_debit` only. A type that declares a secure field (`sepa_debit`) sends the element's tokenized credential as `token`. `us_bank_account` sends nothing here — the buyer links the account after confirm, through the hosted bank-connection flow the payment parks behind.", "properties": { "token": { "description": "The Basis Theory token the element vaulted the account details into. Required for types declaring a secure field; rejected for types that collect after confirm.", "example": "bt_tok_sepa", "type": "string" } }, "type": "object" }, "card": { "description": "Category `card` only. Exactly one of `token` or `token_intent`; display fields ride alongside.", "properties": { "brand": { "description": "Display-safe card brand from the collection surface, e.g. `visa`.", "example": "visa", "type": [ "string", "null" ] }, "last4": { "description": "Display-safe last four digits from the collection surface.", "example": "4242", "type": [ "string", "null" ] }, "token": { "description": "An element-assembled, expiring Basis Theory token. Provide this or token_intent.", "example": "bt_tok_456", "type": "string" }, "token_intent": { "description": "A Basis Theory token intent. Provide this or token.", "example": "bt_ti_123", "type": "string" } }, "type": "object" }, "category": { "description": "The payload shape the surface collected. Must be the category the type resolves to — it is derived server-side and a mismatch is rejected. `saved` and `balance` are the exceptions: they name a method already on file or a spendable balance rather than one collected here.", "enum": [ "card", "wallet", "bank_debit", "bank_transfer", "voucher", "redirect", "crypto", "balance", "in_app_purchase", "saved" ], "example": "card", "type": "string" }, "google_pay": { "description": "Type `google_pay` (category `wallet`) only.", "properties": { "token_intent": { "description": "The Basis Theory token intent the Google Pay sheet flow vaulted the raw wallet token into.", "type": "string" } }, "required": [ "token_intent" ], "type": "object" }, "payer_document": { "description": "The buyer's identity document when the charge currency has a payer_document_requirements entry for this method, such as ARS card, MODO, or Rapipago. This is independent of the method category.", "properties": { "token": { "description": "The Basis Theory token containing the identity-document number.", "example": "20123456", "type": "string" }, "type": { "description": "The selected identity-document type from the method's payer_document_requirements entry.", "enum": [ "dni", "cuil", "cuit", "passport", "cc", "ci", "rut", "curp", "rfc" ], "example": "dni", "type": "string" } }, "required": [ "type", "token" ], "type": "object" }, "saved": { "description": "Category `saved` only. Names one of the buyer's own stored payment methods. Requires a buyer credential — the wallet read is scoped to that account, so another user's id reads as not found.", "properties": { "payment_method": { "description": "The stored payment method to charge — a payment method id from GET /payment_methods.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "payment_method" ], "type": "object" }, "type": { "description": "The payment method type, for example `card` or `ideal`. Required for every category except `saved` and `balance`, where it is read from the referenced method.", "example": "card", "type": "string" } }, "required": [ "category" ], "type": "object" }, "return_url": { "description": "Where redirect flows send the buyer, carried onto the confirm that consumes this token.", "type": [ "string", "null" ] }, "setup_future_usage": { "description": "The save-consent state your surface displayed when the buyer confirmed. Confirm may vault only if attested here.", "enum": [ "off_session", "on_session", null ], "example": "off_session", "type": [ "string", "null" ] } }, "required": [ "account_id", "payment_method" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationToken" } } }, "description": "confirmation token created from a card token intent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a token on a method that collects after confirm" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "saved method requested without a credential" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential does not carry the payment methods scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ {}, { "bearerAuth": [ "member:payment_methods:use" ] } ], "summary": "Create Confirmation Token", "tags": [ "Confirmation Tokens" ] }, "x-whop-surface": "native" }, "/confirmation_tokens/{id}": { "get": { "description": "Retrieves a token's display-safe preview — never the underlying payment credential. Public and rate-limited: the account_id query param must match the account the token was minted for.", "operationId": "retrieveConfirmationToken", "parameters": [ { "description": "The account (biz_) the token was minted for.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationToken" } } }, "description": "confirmation token retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account mismatch" } }, "security": [], "summary": "Retrieve Confirmation Token", "tags": [ "Confirmation Tokens" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Confirmation token ID, prefixed `ctok_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "completed", "required": false, "schema": { "description": "Whether to filter for completed or in-progress lesson interactions.", "type": "boolean" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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": "Retrieve the deposit methods for an account, including crypto and bank transfer.", "operationId": "createDeposit", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Amount to prefill on hosted deposit page.", "example": 50.0, "type": "number" }, "destination": { "description": "Destination account ID or wallet address. Object form is supported for compatibility. Any business resolves by its account ID without authentication; a user account resolves only for that same authenticated user.", "oneOf": [ { "type": "string" }, { "properties": { "account_id": { "description": "Destination account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "address": { "description": "Destination wallet address.", "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": "string" }, "network": { "description": "Destination wallet network.", "enum": [ "ethereum", "polygon", "base", "solana" ], "example": "ethereum", "type": "string" } }, "type": "object" } ] }, "metadata": { "additionalProperties": true, "description": "Metadata to include with the deposit response.", "example": { "invoice": "SHINE-1042" }, "type": "object" }, "network": { "description": "Destination network override. Defaults to the destination wallet's own network.", "enum": [ "ethereum", "polygon", "base", "solana", null ], "example": "ethereum", "type": [ "string", "null" ] } }, "required": [ "destination" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID of the destination owner. Null for raw wallet address destinations.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "Requested deposit amount.", "example": "50.00", "type": "string" }, "hosted_url": { "description": "URL of the hosted deposit page. Only present for business destinations.", "example": "https://whop.com/deposit/biz_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Metadata from the request.", "example": { "invoice": "SHINE-1042" }, "type": "object" }, "methods": { "description": "Available deposit methods for destination.", "properties": { "bank": { "description": "Bank deposit details. Only present when bank deposits are active for the destination account.", "properties": { "currencies": { "description": "Bank transfer currencies available for this deposit.", "items": { "properties": { "account_number": { "description": "Bank account number for deposits in this currency.", "example": "8825310472", "type": [ "string", "null" ] }, "currency": { "description": "Currency supported by these bank instructions.", "example": "USD", "type": "string" }, "deposit_bank_address": { "description": "Receiving bank address.", "example": "2115 Linwood Avenue, Fort Lee, New Jersey 07024", "type": [ "string", "null" ] }, "deposit_bank_name": { "description": "Receiving bank name.", "example": "Cross River Bank", "type": [ "string", "null" ] }, "deposit_beneficiary_name": { "description": "Beneficiary name to use for transfer.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "deposit_reference": { "description": "Reference to include with bank transfer.", "example": "SHINE-1042", "type": [ "string", "null" ] }, "rails": { "description": "Active deposit rails for this currency.", "items": { "enum": [ "ach", "wire", "sepa", "fps", "chaps" ], "example": "wire", "type": "string" }, "type": "array" }, "routing_number": { "description": "Bank routing number for deposits in this currency.", "example": "021214891", "type": [ "string", "null" ] }, "swift_bic": { "description": "SWIFT/BIC code for international wires, when available.", "example": "CRBAUS33", "type": [ "string", "null" ] } }, "required": [ "currency", "account_number", "routing_number", "deposit_bank_name", "deposit_bank_address", "deposit_beneficiary_name", "deposit_reference", "swift_bic", "rails" ], "type": "object" }, "type": "array" } }, "required": [ "currencies" ], "type": [ "object", "null" ] }, "crypto": { "description": "Crypto networks available for this deposit, each with its on-chain deposit address and the tokens accepted on that network.", "items": { "properties": { "deposit_address": { "description": "Address to send funds to on this network. Null when the provider has not issued one yet.", "example": "soladdr", "type": [ "string", "null" ] }, "icon_url": { "description": "Network icon URL.", "example": "https://whop.com/crypto/solana.svg", "type": [ "string", "null" ] }, "name": { "description": "Network display name.", "enum": [ "Ethereum", "Solana", "Base", "BNB Smart Chain", "Hyperliquid", "Hypercore", "MegaETH", "Polygon", "Plasma", "Arbitrum" ], "example": "Solana", "type": "string" }, "supported_currencies": { "description": "Tokens accepted for deposit on this network.", "items": { "properties": { "icon_url": { "description": "Token icon URL. Null when no icon is available.", "example": "https://whop.com/crypto/ethereum.svg", "type": [ "string", "null" ] }, "name": { "description": "Token symbol.", "enum": [ "ARB", "BNB", "ETH", "EURC", "HYPE", "PYUSD", "SOL", "USD1", "USDC", "USDC.e", "USDG", "USDT", "USDT0", "USDe", "USDm", "XO", "XPL", "pUSD", "wETH" ], "example": "wETH", "type": "string" } }, "required": [ "name", "icon_url" ], "type": "object" }, "type": "array" } }, "required": [ "name", "deposit_address", "icon_url", "supported_currencies" ], "type": "object" }, "type": "array" } }, "required": [ "bank", "crypto" ], "type": "object" }, "object": { "enum": [ "deposit" ], "example": "deposit", "type": "string" } }, "required": [ "object", "account_id", "hosted_url", "methods", "metadata" ], "type": "object" } } }, "description": "deposit created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ {}, { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Create Deposit", "tags": [ "Deposits" ] }, "x-whop-surface": "native" }, "/dispute_alerts": { "get": { "description": "Lists the dispute alerts and early fraud warnings across the accounts you can read.", "operationId": "listDisputeAlerts", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Only alerts on this account's payments (`biz_` tag). Omit it to cover every account you can read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only alerts on this payment (`pay_` tag). A payment can carry several.", "in": "query", "name": "payment_id", "required": false, "schema": { "type": "string" } }, { "description": "Only alerts of this kind. `early_fraud_warning` for issuer fraud reports, `dispute_alert` for pre-dispute notices, `rapid_dispute_resolution` for Visa RDR cases the network already closed.", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "early_fraud_warning", "dispute_alert", "rapid_dispute_resolution" ], "type": "string" } }, { "description": "The number of alerts to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns alerts after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of alerts to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns alerts before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort alerts by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "reported_at", "amount" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only alerts Whop received before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only alerts Whop received after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DisputeAlert" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "dispute alerts listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized type filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute-alert-read scope" } }, "security": [ { "bearerAuth": [ "payment:dispute_alert:read" ] } ], "summary": "List Dispute Alerts", "tags": [ "Dispute alerts" ] }, "x-whop-surface": "native" }, "/dispute_alerts/{id}": { "get": { "description": "Retrieves a single dispute alert or early fraud warning by ID.", "operationId": "retrieveDisputeAlert", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The dispute alert ID, prefixed `dspa_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeAlert" } } }, "description": "dispute alert returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute-alert-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "a record-only issuer signal Whop does not forward" } }, "security": [ { "bearerAuth": [ "payment:dispute_alert:read" ] } ], "summary": "Retrieve Dispute Alert", "tags": [ "Dispute alerts" ] }, "x-whop-surface": "native" }, "/disputes": { "get": { "description": "Lists the disputes across the accounts you can read.", "operationId": "listDisputes", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Only disputes filed against this account (`biz_` tag). Omit it to cover every account you can read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The number of disputes to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns disputes after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of disputes to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns disputes before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort disputes by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "amount", "evidence_due_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only disputes in these statuses. Repeat the parameter to pass several — one paginated list covers all of them. Covers both chargebacks and inquiries at each stage. A `needs_response` dispute whose evidence deadline has passed reports and filters as `under_review` instead.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "needs_response", "under_review", "won", "lost", "closed" ], "example": "needs_response", "type": "string" }, "type": "array" } }, { "description": "Only disputes in this three-letter ISO currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Dispute" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "disputes listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute-read scope" } }, "security": [ { "bearerAuth": [ "payment:dispute:read" ] } ], "summary": "List Disputes", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/summary": { "get": { "description": "Totals up the same disputes the list returns, so you can build status tabs and totals without paging through them.", "operationId": "retrieveDisputeSummary", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Which breakdowns to return, keyed by these names under `groups`. Repeat the parameter to ask for several; omit it for all of them.", "in": "query", "name": "groups", "required": false, "schema": { "items": { "enum": [ "status", "currency" ], "example": "status", "type": "string" }, "type": "array" } }, { "description": "Only disputes filed against this account (`biz_` tag). Omit it to cover every account you can read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes in these statuses. Repeat the parameter to pass several. A `needs_response` dispute whose evidence deadline has passed reports and filters as `under_review` instead.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "needs_response", "under_review", "won", "lost", "closed" ], "example": "needs_response", "type": "string" }, "type": "array" } }, { "description": "Only disputes in this three-letter ISO currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groups": { "description": "One entry per requested breakdown, keyed by the field it groups on. A field you did not ask for is absent.", "properties": { "currency": { "additionalProperties": { "type": "integer" }, "description": "How many of the matching disputes are in each currency, keyed by three-letter ISO code. Only currencies with at least one dispute are present.", "example": { "usd": 1 }, "type": "object" }, "status": { "description": "How many of the matching disputes are in each status. Every status is present, including those with a count of zero.", "properties": { "closed": { "example": 0, "type": "integer" }, "lost": { "example": 0, "type": "integer" }, "needs_response": { "example": 1, "type": "integer" }, "under_review": { "example": 0, "type": "integer" }, "won": { "example": 0, "type": "integer" } }, "required": [ "needs_response", "under_review", "won", "lost", "closed" ], "type": "object" } }, "type": "object" }, "total": { "description": "How many disputes match the filters.", "example": 1, "type": "integer" } }, "required": [ "total", "groups" ], "type": "object" } } }, "description": "summary returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized breakdown" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "payment:dispute:read" ] } ], "summary": "Retrieve Dispute Summary", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/{id}": { "get": { "description": "Retrieves a single dispute.", "operationId": "retrieveDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" } }, "security": [ { "bearerAuth": [ "payment:dispute:read" ] } ], "summary": "Retrieve Dispute", "tags": [ "Disputes" ] }, "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Edits a dispute's evidence, while it is still editable. Sending it is a separate call.", "operationId": "updateDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "evidence": { "description": "The evidence packet to send to the processor. Only the fields you provide are changed.", "properties": { "access_activity_log": { "description": "Log of the customer's access to the product, such as sign-in or download activity.", "example": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address the customer provided at checkout.", "example": "4180 Burnet Rd, Austin, TX 78756, US", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "cancellation_policy_disclosure": { "description": "How the cancellation policy was shown to the customer before purchase.", "example": "Shown at checkout and again in the booking confirmation email.", "type": [ "string", "null" ] }, "customer_communication_attachment": { "description": "Correspondence with the customer, or proof they used the product.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "customer_email_address": { "description": "The email address the customer used at checkout.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's name as given at checkout.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "notes": { "description": "Any additional context for the processor reviewing the dispute.", "example": "Two-day ceramic coating completed and collected. Before and after photos attached.", "type": [ "string", "null" ] }, "product_description": { "description": "What the customer purchased, in the seller's own words.", "example": "Two-stage paint correction with a three-year ceramic coating.", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "refund_policy_disclosure": { "description": "How the refund policy was shown to the customer before purchase.", "example": "Linked from the booking page and accepted at checkout.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "Why a refund was refused, when one was requested and denied.", "example": "Work was completed and the vehicle collected, so the deposit is non-refundable.", "type": [ "string", "null" ] }, "service_date": { "description": "When the product or service was delivered.", "example": "2026-01-01", "type": [ "string", "null" ] }, "uncategorized_attachment": { "description": "Supporting evidence that does not fit the other categories.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the dispute's evidence can no longer be edited" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Update Dispute", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/{id}/submit": { "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Sends a dispute's evidence to the payment processor. This is final — it cannot be edited or sent again.", "operationId": "submitDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute submitted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the dispute's evidence can no longer be submitted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Submit Dispute", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/disputes/{id}/upload_evidence": { "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Replaces the full set of uploaded evidence documents on a dispute, beyond the four fixed evidence slots. Upload files through `POST /files` and reference them by `id`, or send the files as multipart file parts to upload and attach in one call. Send every document the packet should carry — up to 10, 10MB each and 25MB in total; an empty list removes them all. Accepted content types: application/pdf, application/json, image/jpeg, image/png, image/webp — any other type is rejected.", "operationId": "uploadDisputeEvidence", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "documents": { "description": "The full set of evidence documents the dispute should carry. Replaces all previously uploaded documents.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What kind of evidence the document is.", "enum": [ "return_policy", "shipping_policy", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription" ], "example": "product_image", "type": "string" }, "file": { "description": "The file itself. Send it as a file part to upload and attach in one call, or use `id`/`direct_upload_id` for a file that is already stored.", "format": "binary", "type": "string" }, "id": { "description": "The ID of a file already stored on Whop, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "document_type" ], "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "documents" ], "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "documents": { "description": "The full set of evidence documents the dispute should carry. Replaces all previously uploaded documents.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What kind of evidence the document is.", "enum": [ "return_policy", "shipping_policy", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription" ], "example": "product_image", "type": "string" }, "file": { "description": "The file itself. Send it as a file part to upload and attach in one call, or use `id`/`direct_upload_id` for a file that is already stored.", "format": "binary", "type": "string" }, "id": { "description": "The ID of a file already stored on Whop, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "document_type" ], "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "documents" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "evidence documents attached" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unknown document_type" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Upload Dispute Evidence", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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.\n\nRequired permissions:\n - `dms:channel:manage`", "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" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this direct message channel. Webhooks still fire.", "type": [ "boolean", "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" }, "429": { "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": "Too many requests" }, "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 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 (one of):\n - `dms:channel:manage`\n - `support_chat:create`", "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat:create" ] } ], "summary": "Delete dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing DM channel.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat: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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat: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 (one of):\n - `dms:channel:manage`\n - `support_chat:create`", "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat:create" ] } ], "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 (one of):\n - `dms:read`\n - `support_chat: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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat: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 (one of):\n - `dms:message:manage`\n - `support_chat:message:create`", "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" }, "429": { "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": "Too many requests" }, "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:message:manage" ] }, { "bearerAuth": [ "support_chat:message:create" ] } ], "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 (one of):\n - `dms:read`\n - `support_chat:read`", "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Delete dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing DM member.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat: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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat: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 (one of):\n - `dms:read`\n - `support_chat:read`", "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for results. Defaults to descending." }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/EntriesSortableColumns", "description": "The column to sort waitlist entries by. Defaults to creation date." }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/events": { "get": { "description": "Lists identity-linked events, most recent first by default. Pass identifier for one person's journey, or omit it to list events for an account within an explicit time range. Pass direction=asc to read a journey forwards from where it starts. Events are shaped like the POST /events intake: attribution in context, identity in user.", "operationId": "listEvents", "parameters": [ { "description": "Any hard identifier of the person: a person ID (prsn_*), user ID, email, phone number, or a tracking cookie value (wuid, anonymous ID, fbp/fbc/ttp/ga). Omit to list recent events for the account.", "in": "query", "name": "identifier", "required": false, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Optional for account API keys; required for credentials that can access multiple accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time range as an ISO 8601 timestamp. Required when identifier is omitted.", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of the time range as an ISO 8601 timestamp. Required when identifier is omitted; otherwise defaults to now.", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The number of events to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching events after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching events before a later page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The order events are returned in by time. Defaults to desc (most recent first); asc reads a journey forwards from where it starts. after and before always page forwards and backwards through that order.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Full event names to filter by, comma-separated (payment.completed, pixel.lead, pixel.page, pixel.custom:) — the same vocabulary the events / people metrics use.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } }, { "description": "Canonical source path, exact or with a trailing :* prefix (whop::*, ext:meta:*, referrer:, direct). Restricts the list to conversion targets attributed to that source — the debuggability twin of a metric cell's source parameter. A whop:... source combined with non-conversion event names (event=pixel.page) instead lists the events whose ad click resolved to that entity — the page views an ad drove.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model for the source filter (defaults to last_touch).", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Country codes to filter by, comma-separated.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Cities to filter by, comma-separated.", "in": "query", "name": "city", "required": false, "schema": { "type": "string" } }, { "description": "Device families to filter by, comma-separated (e.g. iPhone, Mac).", "in": "query", "name": "device", "required": false, "schema": { "type": "string" } }, { "description": "Browser families to filter by, comma-separated (e.g. Chrome, Mobile Safari).", "in": "query", "name": "browser", "required": false, "schema": { "type": "string" } }, { "description": "Operating system families to filter by, comma-separated (e.g. iOS, Windows).", "in": "query", "name": "os", "required": false, "schema": { "type": "string" } }, { "description": "utm_source values to filter by, comma-separated.", "in": "query", "name": "utm_source", "required": false, "schema": { "type": "string" } }, { "description": "Page hostnames to filter by, comma-separated.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Page paths to filter by, comma-separated.", "in": "query", "name": "page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "context": { "properties": { "ad_campaign_id": { "example": "adcamp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "ad_click_id": { "description": "Stable identity for the ad click this event belongs to. Every event from one click carries the same value, so events group into clicks without re-deriving them.", "example": "IwAR123", "type": [ "string", "null" ] }, "ad_click_type": { "description": "How the ad click was identified: the network's click-id param (`fbclid`, `ttclid`, `gclid`, `gbraid`, `wbraid`, `twclid`) or `synthetic` when the click carried none.", "example": "fbclid", "type": [ "string", "null" ] }, "ad_id": { "example": "ad_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "ad_set_id": { "example": "adgrp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source_type": { "description": "How this event counts as an acquisition touch, using the same rule attribution credits a conversion with. `ad_click` and `lead_form` resolved to a Whop ad; `external_ad_click` is a paid click on a campaign run outside Whop; `referrer` is organic. Null when the event is not a touch.", "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", null ], "example": "ad_click", "type": [ "string", "null" ] }, "utm_campaign": { "example": "brand", "type": [ "string", "null" ] }, "utm_content": { "example": "creative", "type": [ "string", "null" ] }, "utm_medium": { "example": "paid", "type": [ "string", "null" ] }, "utm_source": { "example": "google", "type": [ "string", "null" ] }, "utm_term": { "example": "keyword", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "custom_name": { "example": "coating_deposit_paid", "type": [ "string", "null" ] }, "event_id": { "example": "evt_124", "type": "string" }, "event_name": { "example": "pixel.custom", "type": "string" }, "event_time": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "example": "evt_124", "type": "string" }, "path": { "example": "/checkout/complete", "type": [ "string", "null" ] }, "person_id": { "example": "prsn_123", "type": "string" }, "questions": { "items": { "properties": { "answer": { "example": "SUV", "type": [ "string", "null" ] }, "id": { "example": "q_2", "type": [ "string", "null" ] }, "key": { "example": "vehicle_type", "type": [ "string", "null" ] }, "options": { "items": { "example": "Truck", "type": "string" }, "type": [ "array", "null" ] }, "question": { "example": "What vehicle are we detailing?", "type": [ "string", "null" ] }, "type": { "example": "custom", "type": [ "string", "null" ] } }, "type": "object" }, "type": [ "array", "null" ] }, "recommended_action_chain_id": { "type": [ "string", "null" ] }, "recommended_action_shown_position": { "type": [ "integer", "null" ] }, "referrer_url": { "example": "https://google.com", "type": [ "string", "null" ] }, "related": { "description": "Hydrated details for the records this event references. Only present keys resolved.", "properties": { "account": { "properties": { "id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ad": { "description": "The Whop ad this event's click resolved to.", "properties": { "id": { "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "thumbnail_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "example": "Ceramic coating — before/after reel", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ad_campaign": { "description": "The Whop ad campaign this event's click resolved to, read from the ad entity tree rather than the click's url params.", "properties": { "id": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "example": "meta", "type": [ "string", "null" ] }, "title": { "example": "Ceramic coating — spring push", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ad_group": { "description": "The Whop ad group this event's click resolved to.", "properties": { "id": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "title": { "example": "Austin — SUV owners", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "app": { "properties": { "domain_id": { "example": "whopappdomain0000001", "type": [ "string", "null" ] }, "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "title": { "example": "Shine Time Booking", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "audience": { "description": "The saved audience this event came from. Present on the identify events an audience ingest writes for each of its members.", "properties": { "audience_type": { "enum": [ "custom", "lookalike", null ], "example": "custom", "type": [ "string", "null" ] }, "file_name": { "example": "shine-time-customers.csv", "type": [ "string", "null" ] }, "id": { "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "source_type": { "enum": [ "csv_upload", "people_filter", null ], "example": "csv_upload", "type": [ "string", "null" ] }, "title": { "example": "Austin ceramic coating leads", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "payment": { "properties": { "card_brand": { "example": "visa", "type": [ "string", "null" ] }, "card_last4": { "example": "4242", "type": [ "string", "null" ] }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "provider": { "example": "stripe", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "plan": { "properties": { "billing_period": { "example": 30, "type": [ "integer", "null" ] }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "id": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "example": 0.0, "type": [ "number", "null" ] }, "renewal_price": { "example": 59.0, "type": [ "number", "null" ] }, "title": { "example": "Unlimited Wash Club", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "product": { "properties": { "id": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "route": { "example": "ceramic-coating-package", "type": [ "string", "null" ] }, "title": { "example": "Ceramic Coating Package", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "user": { "properties": { "avatar_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "type": [ "object", "null" ] }, "total_usd_amount": { "example": 249.0, "type": [ "number", "null" ] }, "url": { "example": "https://shinetime.example/checkout/complete", "type": [ "string", "null" ] }, "user": { "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "example": "US", "type": [ "string", "null" ] }, "email": { "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Dana", "type": [ "string", "null" ] }, "last_name": { "example": "Whitfield", "type": [ "string", "null" ] }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "phone": { "example": "5551234567", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "value": { "example": 249.0, "type": [ "number", "null" ] } }, "required": [ "id", "event_id", "event_name", "person_id", "event_time" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "events listed oldest first" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid direction" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "List Events", "tags": [ "Events" ] }, "post": { "description": "Tracks a conversion or engagement event for an account.", "operationId": "createEvent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateConversion", "properties": { "account_id": { "description": "The account to associate with this event.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "action_source": { "description": "Where the event originated.", "oneOf": [ { "description": "The channel where an event originated", "enum": [ "email", "website", "app", "phone_call", "chat", "physical_store", "system_generated", "business_messaging", "other" ], "example": "website", "type": "string" }, { "type": "null" } ] }, "app_build_id": { "description": "The build of the hosted app that served the page where the event occurred.", "example": "apbu_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "app_id": { "description": "The hosted app that served the page where the event occurred.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "context": { "description": "Tracking and attribution context.", "properties": { "ad_campaign_id": { "description": "Ad campaign ID.", "example": "23851234567890123", "type": [ "string", "null" ] }, "ad_id": { "description": "Ad ID.", "example": "23851234567890125", "type": [ "string", "null" ] }, "ad_set_id": { "description": "Ad set ID.", "example": "23851234567890124", "type": [ "string", "null" ] }, "fbc": { "description": "Facebook click cookie (_fbc, format fb.1.{timestamp}.{fbclid}).", "example": "fb.1.xxxxxxxxxx.IwAR0shine", "type": [ "string", "null" ] }, "fbclid": { "description": "Facebook click ID.", "example": "IwAR0shineTimeAutoDetailing", "type": [ "string", "null" ] }, "fbp": { "description": "Facebook browser pixel ID.", "example": "fb.1.xxxxxxxxxx.xxxxxxxxxx", "type": [ "string", "null" ] }, "fingerprint": { "description": "Client-side device fingerprint.", "example": "fp_4d19c7", "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.", "example": "GA1.1.xxxxxxxxxx.xxxxxxxxxx", "type": [ "string", "null" ] }, "gbraid": { "description": "Google Ads gbraid click ID (iOS privacy).", "example": "0AAAAA-shinetime", "type": [ "string", "null" ] }, "gclid": { "description": "Google click ID.", "example": "Cj0KCQiAshinetime", "type": [ "string", "null" ] }, "ig_sid": { "description": "Instagram session ID.", "example": "ig_shinetime_1", "type": [ "string", "null" ] }, "ip_address": { "description": "IP address.", "example": "1.2.3.4", "type": [ "string", "null" ] }, "language": { "description": "Browser language (e.g. en-US).", "example": "en-US", "type": [ "string", "null" ] }, "li_fat_id": { "description": "LinkedIn click ID.", "example": "lifat-shinetime", "type": [ "string", "null" ] }, "msclkid": { "description": "Microsoft Advertising (Bing) click ID.", "example": "a1b2c3d4shine", "type": [ "string", "null" ] }, "rdt_cid": { "description": "Reddit click ID.", "example": "t2_shinetime", "type": [ "string", "null" ] }, "sc": { "description": "Whop SC identifier.", "example": "BDFB1C71", "type": [ "string", "null" ] }, "sccid": { "description": "Snapchat click ID.", "example": "sccid-shinetime", "type": [ "string", "null" ] }, "screen_resolution": { "description": "Screen resolution (e.g. 1920x1080).", "example": "390x844", "type": [ "string", "null" ] }, "timezone": { "description": "IANA timezone (e.g. America/New_York).", "example": "America/Chicago", "type": [ "string", "null" ] }, "ttclid": { "description": "TikTok click ID.", "example": "E.C.P.ttclid.shine", "type": [ "string", "null" ] }, "ttp": { "description": "TikTok pixel ID.", "example": "2ShineTimeTtp", "type": [ "string", "null" ] }, "twclid": { "description": "X (Twitter) click ID.", "example": "twclid-shinetime", "type": [ "string", "null" ] }, "user_agent": { "description": "Browser user agent string.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15", "type": [ "string", "null" ] }, "utm_campaign": { "description": "UTM campaign parameter.", "example": "ceramic-coating-spring", "type": [ "string", "null" ] }, "utm_content": { "description": "UTM content parameter.", "example": "carousel-a", "type": [ "string", "null" ] }, "utm_id": { "description": "UTM ID parameter.", "example": "utm_88213", "type": [ "string", "null" ] }, "utm_medium": { "description": "UTM medium parameter.", "example": "cpc", "type": [ "string", "null" ] }, "utm_source": { "description": "UTM source parameter.", "example": "google", "type": [ "string", "null" ] }, "utm_term": { "description": "UTM term parameter.", "example": "ceramic coating austin", "type": [ "string", "null" ] }, "wbraid": { "description": "Google Ads wbraid click ID (iOS privacy).", "example": "Cj0KCQjw-wbraid-shine", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "currency": { "description": "ISO 4217 currency code.", "oneOf": [ { "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" ], "example": "usd", "type": "string" }, { "type": "null" } ] }, "custom_name": { "description": "Custom event name when event_name is 'custom'. Maximum 35 chars for this value.", "example": "coating_deposit_paid", "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": { "description": "The type of event.\n\nUse a standard event (lead, submit_application, contact, complete_registration, schedule, view_content, add_to_cart) or pass your own name directly for a custom event.", "example": "coating_deposit_paid", "type": "string" }, "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.", "example": "https://www.google.com/", "type": [ "string", "null" ] }, "resumed": { "description": "For 'page' events: true when the page was restored from the back/forward cache.", "example": false, "type": [ "boolean", "null" ] }, "source": { "description": "For 'identify' events: where the identity was captured (url, form, manual, iframe).", "example": "website", "type": [ "string", "null" ] }, "title": { "description": "For 'page' events: the document title.", "example": "Ceramic coating quote request", "type": [ "string", "null" ] }, "url": { "description": "The URL where the event occurred.", "example": "https://shinetime.example/quote", "type": [ "string", "null" ] }, "user": { "description": "User identity and profile data.", "properties": { "anonymous_id": { "description": "An anonymous identifier for the user.", "example": "anon_8f2c41", "type": [ "string", "null" ] }, "birthdate": { "description": "Date of birth (YYYY-MM-DD).", "example": "1990-01-15", "type": [ "string", "null" ] }, "city": { "description": "City.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Country.", "example": "US", "type": [ "string", "null" ] }, "email": { "description": "Email address.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "external_id": { "description": "An external identifier for the user.", "example": "crm_8842", "type": [ "string", "null" ] }, "first_name": { "description": "First name.", "example": "Dana", "type": [ "string", "null" ] }, "gender": { "description": "Gender.", "oneOf": [ { "description": "Gender", "enum": [ "male", "female" ], "example": "female", "type": "string" }, { "type": "null" } ] }, "last_name": { "description": "Last name.", "example": "Whitfield", "type": [ "string", "null" ] }, "linked_anonymous_id": { "description": "A second anonymous identifier to link to this user (e.g. captured across an iframe boundary).", "example": "anon_1b9de0", "type": [ "string", "null" ] }, "linked_wuid": { "description": "A wuid from a linked frame, captured across an iframe boundary.", "example": "user_xxxxxxxxxxxxxx", "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.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "phone": { "description": "Phone number.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State or region.", "example": "TX", "type": [ "string", "null" ] }, "user_id": { "description": "The Whop user ID.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "Username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "value": { "description": "Monetary value associated with the event.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "account_id", "event_name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "example": "evnt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "description": "event created" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "event:create" ] }, {} ], "summary": "Create Event", "tags": [ "Events" ] }, "x-whop-surface": "native" }, "/events/pulse": { "get": { "description": "Returns a fully anonymized feed of recent platform-wide money movement, most recent first: purchases, affiliate commissions, card and ad spend, app revenue, off-platform sales, wallet deposits, card loads, claimed drops, transfers between accounts, and referral bonuses. Items carry only a `type`, the underlying event name, a USD amount, a coarse location under `user`, and a timestamp coarsened to the start of the minute; missing fields are omitted, not nulled. The payload is identical for every caller; no auth is required.", "operationId": "retrievePulse", "parameters": [ { "description": "Filter to one or more types, comma separated — for example `purchase,card_spend`. These are the item's `type`, not its `event_name`: several types share the `ledger_line.created` event name. Omit for every type in the feed. Values outside the feed's own set are rejected.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } }, { "description": "The number of events to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching events after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching events before a later page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Recent anonymized money-movement events, newest first.", "items": { "properties": { "event_name": { "description": "The underlying event recorded. Every movement on this feed is a ledger line, so switch on `type` rather than this.", "enum": [ "ledger_line.created" ], "example": "ledger_line.created", "type": "string" }, "event_time": { "description": "When the event happened, coarsened to the start of the minute.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "total_usd_amount": { "description": "The USD amount of the event.", "example": 45.5, "type": [ "number", "null" ] }, "type": { "description": "What moved: a purchase, an affiliate commission, Whop card spend, ad spend, app revenue, an off-platform sale, a wallet deposit, a card load, a claimed drop, a transfer between accounts, or a referral bonus.", "enum": [ "purchase", "affiliate_commission", "card_spend", "ad_spend", "app_revenue", "off_platform_sale", "deposit", "card_load", "airdrop_claim", "transfer", "referral_bonus" ], "example": "purchase", "type": "string" }, "user": { "description": "Coarse location, shaped like the event `user` block. It belongs to the owner of the wallet the money moved into or out of — the party the event is about, never their counterparty. Omitted entirely when nothing is known.", "properties": { "city": { "description": "City name. Omitted when unknown.", "example": "Austin", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code. Omitted when unknown.", "example": "US", "type": "string" } }, "type": "object" } }, "required": [ "event_name", "type", "event_time" ], "type": "object" }, "maxItems": 50, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "pulse feed filtered to one type" }, "400": { "description": "event given as an event name rather than a type" } }, "security": [], "summary": "Retrieve the pulse feed", "tags": [ "Events" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/events/validate_pixel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Checks whether the Whop pixel is installed for an account. Recent pixel events count as proof on their own, so an account that has sent data lately comes back installed without a `url`. Pass a `url` and events from that page settle it; conversion events are also read across the hostname because they commonly fire on a later confirmation page. If the requested page hasn't sent any events lately, it is fetched and read for the pixel and conversion events wired on it. `installed` is only true when the pixel was actually seen — in the account's events or in the page.", "operationId": "validatePixel", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to check. Defaults to the authenticated account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "A page to read for the pixel, e.g. an ad destination. Omit it to check the account from its events alone.", "example": "https://shinetime.example/checkout/complete", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixelValidation" } } }, "description": "pixel validated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "key lacks the required scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "Validate Pixel", "tags": [ "Events" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this experience. Webhooks still fire.", "type": [ "boolean", "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this experience. Webhooks still fire.", "type": [ "boolean", "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/exports": { "get": { "description": "Lists the exports requested for an account, newest first. Only exports of resources the credential is allowed to export are returned.", "operationId": "listExports", "parameters": [ { "description": "The account to list exports for, prefixed `biz_`. Defaults to the credential's account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return exports of this resource.", "in": "query", "name": "resource", "required": false, "schema": { "enum": [ "ad_campaigns", "ad_groups", "ads", "apps", "audiences", "bounties", "bounty_submissions", "card_transactions", "checkout_configurations", "disputes", "events", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "content_rewards_submissions", "invoices", "cancelation_reasons", "child_companies", "ledger_lines", "withdrawal_lines" ], "type": "string" } }, { "description": "Only return exports in this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "processing", "completed", "failed", "expired" ], "type": "string" } }, { "description": "Only return exports created at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return exports created at or before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Export" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "exports listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unknown status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "holds no export scope on the account" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] }, { "bearerAuth": [ "ad_campaign:basic:read" ] }, { "bearerAuth": [ "audience:basic:read" ] }, { "bearerAuth": [ "bounty:basic:read" ] }, { "bearerAuth": [ "checkout_configuration:basic:read" ] }, { "bearerAuth": [ "child_company:basic:export" ] }, { "bearerAuth": [ "company:authorized_user:read" ] }, { "bearerAuth": [ "company:balance:export" ] }, { "bearerAuth": [ "company:balance:read" ] }, { "bearerAuth": [ "company:basic:read", "member:basic:read", "member:journey:read" ] }, { "bearerAuth": [ "content_rewards:basic:export" ] }, { "bearerAuth": [ "developer:basic:read" ] }, { "bearerAuth": [ "developer:manage_webhook" ] }, { "bearerAuth": [ "invoice:basic:export" ] }, { "bearerAuth": [ "lead:basic:export" ] }, { "bearerAuth": [ "member:basic:export" ] }, { "bearerAuth": [ "payment:basic:export" ] }, { "bearerAuth": [ "payment:dispute:read" ] }, { "bearerAuth": [ "payment:resolution_center_case:export" ] }, { "bearerAuth": [ "payment:resolution_center_case:read" ] }, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payout:destination:read" ] }, { "bearerAuth": [ "payout:transfer:read" ] }, { "bearerAuth": [ "payout:withdrawal:read" ] }, { "bearerAuth": [ "plan:basic:read" ] }, { "bearerAuth": [ "plan:waitlist:export" ] }, { "bearerAuth": [ "promo_code:basic:export" ] }, { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [ "social_account:read" ] }, { "bearerAuth": [ "tracking_link:basic:export" ] } ], "summary": "List Exports", "tags": [ "Exports" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts an asynchronous export of a resource for an account. Returns the export in `pending`; poll `GET /exports/{id}` until `download_url` is set.", "operationId": "createExport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to export from, prefixed `biz_`. Defaults to the credential's account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "columns": { "description": "Column keys to include. Empty means all columns for the resource.", "items": { "example": "member_user_name", "type": "string" }, "type": "array" }, "filters": { "description": "Resource-specific filters. For native REST resources (`payouts`, `transfers`, `products`) these are the resource's own list query params; for dashboard tables they mirror the dashboard table filters.", "example": { "origin_id": "ldgr_x" }, "type": "object" }, "resource": { "description": "The resource to export, e.g. `payouts`, `receipts`, or `members`.", "enum": [ "ad_campaigns", "ad_groups", "ads", "apps", "audiences", "bounties", "bounty_submissions", "card_transactions", "checkout_configurations", "disputes", "events", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "content_rewards_submissions", "invoices", "cancelation_reasons", "child_companies" ], "example": "transfers", "type": "string" }, "timezone": { "description": "IANA timezone for date columns, e.g. `America/New_York`. Defaults to `UTC`.", "example": "America/Chicago", "type": "string" } }, "required": [ "resource" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } }, "description": "export created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "resource is not creatable over REST" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] }, { "bearerAuth": [ "ad_campaign:basic:read" ] }, { "bearerAuth": [ "audience:basic:read" ] }, { "bearerAuth": [ "bounty:basic:read" ] }, { "bearerAuth": [ "checkout_configuration:basic:read" ] }, { "bearerAuth": [ "child_company:basic:export" ] }, { "bearerAuth": [ "company:authorized_user:read" ] }, { "bearerAuth": [ "company:balance:read" ] }, { "bearerAuth": [ "company:basic:read", "member:basic:read", "member:journey:read" ] }, { "bearerAuth": [ "content_rewards:basic:export" ] }, { "bearerAuth": [ "developer:basic:read" ] }, { "bearerAuth": [ "developer:manage_webhook" ] }, { "bearerAuth": [ "invoice:basic:export" ] }, { "bearerAuth": [ "lead:basic:export" ] }, { "bearerAuth": [ "member:basic:export" ] }, { "bearerAuth": [ "payment:basic:export" ] }, { "bearerAuth": [ "payment:dispute:read" ] }, { "bearerAuth": [ "payment:resolution_center_case:export" ] }, { "bearerAuth": [ "payment:resolution_center_case:read" ] }, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payout:destination:read" ] }, { "bearerAuth": [ "payout:transfer:read" ] }, { "bearerAuth": [ "payout:withdrawal:read" ] }, { "bearerAuth": [ "plan:basic:read" ] }, { "bearerAuth": [ "plan:waitlist:export" ] }, { "bearerAuth": [ "promo_code:basic:export" ] }, { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [ "social_account:read" ] }, { "bearerAuth": [ "tracking_link:basic:export" ] } ], "summary": "Create Export", "tags": [ "Exports" ] }, "x-whop-surface": "native" }, "/exports/{id}": { "get": { "description": "Fetches an export's status and, once complete, its download link.", "operationId": "retrieveExport", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } }, "description": "export found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "export not found" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] }, { "bearerAuth": [ "ad_campaign:basic:read" ] }, { "bearerAuth": [ "audience:basic:read" ] }, { "bearerAuth": [ "bounty:basic:read" ] }, { "bearerAuth": [ "checkout_configuration:basic:read" ] }, { "bearerAuth": [ "child_company:basic:export" ] }, { "bearerAuth": [ "company:authorized_user:read" ] }, { "bearerAuth": [ "company:balance:export" ] }, { "bearerAuth": [ "company:balance:read" ] }, { "bearerAuth": [ "company:basic:read", "member:basic:read", "member:journey:read" ] }, { "bearerAuth": [ "content_rewards:basic:export" ] }, { "bearerAuth": [ "developer:basic:read" ] }, { "bearerAuth": [ "developer:manage_webhook" ] }, { "bearerAuth": [ "invoice:basic:export" ] }, { "bearerAuth": [ "lead:basic:export" ] }, { "bearerAuth": [ "member:basic:export" ] }, { "bearerAuth": [ "payment:basic:export" ] }, { "bearerAuth": [ "payment:dispute:read" ] }, { "bearerAuth": [ "payment:resolution_center_case:export" ] }, { "bearerAuth": [ "payment:resolution_center_case:read" ] }, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payout:destination:read" ] }, { "bearerAuth": [ "payout:transfer:read" ] }, { "bearerAuth": [ "payout:withdrawal:read" ] }, { "bearerAuth": [ "plan:basic:read" ] }, { "bearerAuth": [ "plan:waitlist:export" ] }, { "bearerAuth": [ "promo_code:basic:export" ] }, { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [ "social_account:read" ] }, { "bearerAuth": [ "tracking_link:basic:export" ] } ], "summary": "Retrieve Export", "tags": [ "Exports" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The export ID, prefixed `exprt_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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": { "get": { "description": "Returns the files with the given IDs, newest first — fetch a batch in one request instead of retrieving each file individually. Only files you created are returned; IDs that do not exist, or that another credential created, are omitted. A request for up to 100 IDs answers in a single page by default; a larger batch pages at up to 100 files per response — follow `page_info` with the same `file_ids` to walk the rest.", "operationId": "listFiles", "parameters": [ { "description": "The files to return, each prefixed `file_`. Repeat the parameter to pass several, up to 250 per request. Batches of up to 100 answer in one page by default; larger batches page at up to 100 per response.", "explode": true, "in": "query", "name": "file_ids", "required": true, "schema": { "items": { "example": "file_xxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The number of files to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns files after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of files to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns files before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": true, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "files listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Files", "tags": [ "Files" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a file and returns a presigned destination to upload its bytes to. PUT the bytes to `upload_url` (single-part), or to each of `multipart_upload_urls` and then call Complete File Multipart Upload. Once the bytes land the file becomes `ready`, and its ID can be attached wherever a file is accepted — account legal documents, dispute evidence documents. For a step-by-step walkthrough of single-part and multipart uploads, see the [direct file uploads guide](/developer/guides/direct-file-uploads).", "operationId": "createFile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "byte_size": { "description": "The file's size in bytes. Required when `multipart` is `true`. Multipart uploads support at most 10,000 parts of 5MB each (about 50 GB).", "example": 15728640, "type": "integer" }, "filename": { "description": "The name of the file including its extension, e.g. `terms.pdf`.", "example": "terms.pdf", "type": "string" }, "multipart": { "description": "Upload the file in 5MB parts. Required for files larger than 5GB; useful above ~100MB. The file must be larger than 5MB.", "example": true, "type": "boolean" }, "visibility": { "description": "`public` files are served via an unsigned CDN URL — use for assets anyone may see. `private` files are served via a signed, expiring URL — use for sensitive documents. Defaults to `private`.", "enum": [ "public", "private" ], "example": "public", "type": "string" } }, "required": [ "filename" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "file created with a single-part upload destination" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "bad request" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create File", "tags": [ "Files" ] }, "x-whop-surface": "native" }, "/files/{id}": { "get": { "description": "Retrieves a file you uploaded — poll it after uploading the bytes to see `upload_status` become `ready`. Only the creator can retrieve a file this way; a file attached to another resource is read through that resource.", "operationId": "retrieveFile", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "file retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve File", "tags": [ "Files" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the file, prefixed `file_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/files/{id}/complete": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the file, prefixed `file_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Assembles the parts of a multipart upload after every part has been PUT to its presigned URL. Pass the `multipart_upload_id` from Create File and each part's `ETag` response header. For a step-by-step walkthrough of multipart uploads, see the [direct file uploads guide](/developer/guides/direct-file-uploads).", "operationId": "completeFile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "multipart_parts": { "description": "Every uploaded part, in order.", "items": { "properties": { "etag": { "description": "The `ETag` response header from the part's upload.", "example": "etag-1", "type": "string" }, "part_number": { "description": "The 1-based index of the part.", "example": 1, "type": "integer" } }, "required": [ "part_number", "etag" ], "type": "object" }, "type": "array" }, "multipart_upload_id": { "description": "The ID of the multipart upload, returned by Create File.", "example": "upload-id", "type": "string" } }, "required": [ "multipart_upload_id", "multipart_parts" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "multipart upload completed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "bad request" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Complete File Multipart Upload", "tags": [ "Files" ] }, "x-whop-surface": "native" }, "/financial-activity": { "get": { "description": "Returns an account's or user's activity feed: every movement of money in or out.", "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": "When true, aggregates the authenticated user's personal ledger with the businesses they own (owner role with balance read) into one feed. Requires user_id to be the authenticated user; cannot be combined with account_id or the settlement-date filters. Each returned row includes the owning `account`.", "in": "query", "name": "include_owned_accounts", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to include the `resource` field in the response or not. Consider passing `false` if you need a fast response without as many rich details.", "in": "query", "name": "include_resource", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Optional ledger line categories to include. Some categories (for example `onchain_deposit`, which covers inbound crypto deposits such as MoonPay onramps) are only returned when explicitly requested here.", "explode": true, "in": "query", "name": "line_types", "required": false, "schema": { "items": { "enum": [ "ad_budget_release", "ad_campaign_budget", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "affiliate_fee", "airdrop", "airdrop_link_created", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payout", "balance_reservation", "balance_reservation_reversal", "bank_transfer", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_void", "card_spend_refund", "card_unload_deposit", "card_unload_transfer", "company_referral", "connected_account_negative_balance", "cross_border_percentage_fee", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold_adjustment", "dispute_representment_fee", "external_card_load_deposit", "fees", "fraud_prevention_fee", "fx_percentage_fee", "high_risk_merchant_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onchain_deposit", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "passthrough_gmv", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_referral", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_reversal", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payout_fee", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_earning", "promo_reversal", "referral_bonus", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "treasury_payin", "whop_processing_fee", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "example": "onchain_deposit", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Optional direction filter. `money_in` returns positive activity and `money_out` returns negative activity.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "money_in", "money_out" ], "type": "string" } }, { "description": "Optional prefixed resource ID. Returns activity associated with that resource.", "in": "query", "name": "resource_id", "required": false, "schema": { "type": "string" } }, { "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": "Only include rows whose funds became withdrawable on or after this `YYYY-MM-DD` settlement date (UTC), distinct from posted_at. Requires currency.", "in": "query", "name": "available_after", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Only include rows whose funds became withdrawable on or before this `YYYY-MM-DD` settlement date (UTC). Set equal to available_after for a single day. Requires currency.", "in": "query", "name": "available_before", "required": false, "schema": { "format": "date", "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": { "$ref": "#/components/schemas/LedgerActivity" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_2", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_1", "type": [ "string", "null" ] } }, "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" ] }, { "bearerAuth": [ "user:balance:read" ] } ], "summary": "List Financial Activity", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "/financial_reports": { "get": { "description": "Returns a financial report — balance activity, income statement, or balance summary — for an account over a date range.", "operationId": "getFinancialReport", "parameters": [ { "description": "The owning account ID (a biz_ identifier), or `global` for a platform-wide report across all ledger accounts (requires internal admin access).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "The type of financial report to generate.", "in": "query", "name": "report_type", "required": true, "schema": { "enum": [ "balance_summary", "income_statement", "balance_activity" ], "type": "string" } }, { "description": "Filter rows to this currency, for example `usd`. Defaults to `usd` unless `in_currency` is provided.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Aggregate all activity into this display currency via FX conversion.", "in": "query", "name": "in_currency", "required": false, "schema": { "type": "string" } }, { "description": "Start of the report window as an ISO 8601 timestamp (UTC). Required for platform-wide (global) reports.", "in": "query", "name": "from_date", "required": false, "schema": { "type": "string" } }, { "description": "End of the report window as an ISO 8601 timestamp (UTC). Required for platform-wide (global) reports.", "in": "query", "name": "to_date", "required": false, "schema": { "type": "string" } }, { "description": "Grouping granularity for report rows.", "in": "query", "name": "group_by", "required": false, "schema": { "default": "month", "enum": [ "day", "week", "month" ], "type": "string" } }, { "description": "IANA timezone (for example `America/New_York`) used to bucket report periods and to interpret calendar-day boundaries for balance snapshots. Defaults to UTC. from_date/to_date remain exact instants regardless of this setting.", "in": "query", "name": "timezone", "required": false, "schema": { "type": "string" } }, { "description": "Account-level balance activity only: ledger line categories to include.", "explode": true, "in": "query", "name": "line_types", "required": false, "schema": { "items": { "enum": [ "ad_budget_release", "ad_campaign_budget", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "affiliate_fee", "airdrop", "airdrop_link_created", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payout", "balance_reservation", "balance_reservation_reversal", "bank_transfer", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_void", "card_spend_refund", "card_unload_deposit", "card_unload_transfer", "company_referral", "connected_account_negative_balance", "cross_border_percentage_fee", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold_adjustment", "dispute_representment_fee", "external_card_load_deposit", "fees", "fraud_prevention_fee", "fx_percentage_fee", "high_risk_merchant_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onchain_deposit", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "passthrough_gmv", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_referral", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_reversal", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payout_fee", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_earning", "promo_reversal", "referral_bonus", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "treasury_payin", "whop_processing_fee", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Account-level balance activity only: include money moving in or money moving out.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "money_in", "money_out" ], "type": "string" } }, { "description": "Platform-wide (global) reports only: when true, return cumulative balances as of to_date (all history, no lower bound) instead of activity within the period.", "in": "query", "name": "cumulative", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Platform-wide (global) reports only: narrow the report to ledger lines on the ledger account owned by this account ID (a biz_ identifier). Ignored unless account_id is `global`.", "in": "query", "name": "scope_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Balance activity only: include payment costs grouped by payment method and provider.", "in": "query", "name": "include_payment_fee_breakdown", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "beginning_balance": { "example": 11480.02, "type": [ "number", "null" ] }, "currencies": { "description": "Every lifetime cashflow currency, ordered by cashflow volume in the requested period.", "items": { "example": "usd", "type": "string" }, "type": "array" }, "ending_balance": { "example": 23750.55, "type": [ "number", "null" ] }, "fx_excluded_currencies": { "items": { "example": "ngn", "type": "string" }, "type": "array" }, "payment_fee_breakdown": { "description": "Payment costs grouped by customer-facing payment method and provider when requested.", "items": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Payment costs attributed to this payment method." }, "category": { "description": "The customer-facing payment method family or standalone service.", "enum": [ "app_store_payments", "bank_payments", "buy_now_pay_later", "card_payments", "crypto_payments", "fraud_prevention", "local_payments", "other_payment_methods", "subscription_billing", "wallet_payments", "whop_balance", "whop_orchestration" ], "example": "app_store_payments", "type": "string" }, "payment_method": { "description": "The card brand, payment provider, payment rail, or standalone service.", "type": "string" }, "period": { "description": "Start of the time bucket containing these payment costs.", "type": "string" } }, "required": [ "period", "category", "payment_method", "amount" ], "type": "object" }, "type": "array" }, "report_type": { "description": "The report that was generated, echoing the requested `report_type`.", "enum": [ "balance_summary", "income_statement", "balance_activity" ], "example": "balance_summary", "type": "string" }, "rows": { "items": { "properties": { "account_ik_path": { "example": "assets/wallets/wallet/available", "type": [ "string", "null" ] }, "account_name": { "example": "Available balance", "type": [ "string", "null" ] }, "account_type": { "example": "asset", "type": [ "string", "null" ] }, "amount": { "example": 23750.55, "type": "number" }, "grouping": { "description": "The family the row's `line_category` rolls up into. Balance summary rows are always `balance`.", "enum": [ "advertising", "affiliates_and_revshare", "airdrops", "bad_debt", "balance", "clawbacks", "connected_accounts", "crypto", "disputes", "fees", "fx", "legacy", "misc", "other", "payments", "refunds", "reserves", "transfers", "wallets_and_balance", "withdrawals" ], "example": "payments", "type": "string" }, "line_category": { "description": "The ledger line category the row aggregates. Balance summary rows carry the balance bucket instead.", "enum": [ "accelerated_settlement_fee", "account_settlement", "ad_balance_funding_receipt", "ad_budget_release", "ad_campaign_budget", "ad_funding_disbursement", "ad_income_expense", "ad_income_receipt", "ad_network_cost", "ad_network_settlement", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "ad_spend_margin", "ads_card_spread", "affiliate_fee", "aggregated_fee", "airdrop", "airdrop_expense", "airdrop_expense_reversal", "airdrop_link_canceled", "airdrop_link_claimed", "airdrop_link_created", "airdrop_link_funded", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payable", "application_fee_payout", "available", "bad_debt_expense", "bad_debt_offset", "balance_reservation", "balance_reservation_hold", "balance_reservation_release", "balance_reservation_reversal", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_interchange_receivable", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_hold", "card_spend_authorization_void", "card_spend_authorization_void_release", "card_spend_capture", "card_spend_capture_offset", "card_spend_refund", "card_spend_refund_offset", "card_unload_deposit", "card_unload_transfer", "clawback_fee", "clawback_receivable", "clawback_receivable_reversal", "clawback_receivable_settlement", "clawback_receivable_settlement_reversal", "company_referral", "connected_account_clawback", "connected_account_negative_balance", "cross_border_percentage_fee", "crypto", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold", "dispute_hold_adjustment", "dispute_hold_blocked", "dispute_management_fee", "dispute_payable_clearing", "dispute_payable_reversal", "dispute_representment_fee", "dispute_settlement", "dispute_settlement_reversal", "dispute_unreconciled_clearing", "dispute_unreconciled_reversal", "external_account_connection_fee", "external_card_load_deposit", "external_card_load_offset", "fraud_prevention_fee", "fx_gain_loss", "fx_markup", "fx_percentage_fee", "fx_settlement_gain_loss", "high_risk_merchant_fee", "identity_verification_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_payable", "internal_withdrawal_payable_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onchain_deposit", "onchain_deposit_offset", "onchain_swap_offset", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "onchain_withdrawal_offset", "orchestration_percentage_fee", "passthrough_gmv", "passthrough_gmv_offset", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_receivable_clearing", "payment_receivable_reversal", "payment_receivable_settlement", "payment_referral", "payment_referral_payable", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_fee", "payment_refund_reversal", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payment_unreconciled_clearing", "payment_unreconciled_reversal", "payout_fee", "payout_receivable", "payout_subsidy", "payout_unreconciled_clearing", "pending", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_earning", "platform_earning_settlement", "platform_earning_unreconciled_clearing", "promo_reversal", "psp_accelerated_settlement_fee", "psp_account_debit", "psp_account_updater_fee", "psp_adjusted_processing_fee", "psp_authentication_fee", "psp_bank_pull_clearing", "psp_bank_pull_settlement", "psp_billing_fee", "psp_clawback_fee", "psp_clawback_settlement", "psp_clawback_settlement_reversal", "psp_collection_settlement", "psp_commission_fee", "psp_connect_fee", "psp_correction", "psp_currency_conversion_incoming", "psp_currency_conversion_outgoing", "psp_currency_conversion_receivable", "psp_currency_conversion_receivable_clearing", "psp_dispute_alert_fee", "psp_dispute_fee", "psp_dispute_management_fee", "psp_dispute_payable", "psp_external_account_connection_fee", "psp_fixed_fee", "psp_gateway_fee", "psp_identity_verification_fee", "psp_interchange_fee", "psp_invoice_tax_fee", "psp_invoicing_fee", "psp_markup_fee", "psp_network_token_fee", "psp_optimization_fee", "psp_payin_clearing", "psp_payin_settlement", "psp_payment_method_fee", "psp_payment_receivable", "psp_payout_consolidation", "psp_payout_deposit", "psp_payout_fee", "psp_payout_receivable", "psp_payout_receivable_clearing", "psp_payout_settlement", "psp_payout_settlement_reversal", "psp_pool_clearing", "psp_pool_dispute_settlement", "psp_pool_settlement", "psp_processing_fee", "psp_receivable_pooled", "psp_recipient_wallet_load", "psp_refund_fee", "psp_refund_payable", "psp_reserve_hold", "psp_reserve_release", "psp_risk_fee", "psp_scheme_fee", "psp_service_fee", "psp_tax_filing_fee", "psp_tax_service_fee", "psp_terminal_fee", "psp_transfer_settlement", "psp_transfer_settlement_reversal", "psp_treasury_fee", "psp_variable_fee", "psp_withholding_tax", "recipient_wallet_load", "referral_bonus", "refund_payable_clearing", "refund_payable_reversal", "refund_settlement", "refund_settlement_reversal", "refund_unreconciled_clearing", "refund_unreconciled_reversal", "reserve", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_collected", "sales_tax_collected_reversal", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "sales_tax_remitted", "settlement_rounding_variance", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "tax_filing_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "treasury_fee", "treasury_payin", "treasury_payin_receivable", "whop_processing_fee", "whop_swap_fee_received", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_payable", "withdrawal_payable_clearing", "withdrawal_payable_clearing_reversal", "withdrawal_payable_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "example": "payment_gross", "type": "string" }, "line_count": { "example": 214, "type": [ "integer", "null" ] }, "period": { "description": "Start of the time bucket this row covers, truncated to `group_by`.", "example": "2026-05", "type": "string" }, "profit_and_loss_section": { "description": "Which side of the income statement the category falls on, or `null` when it is not a P&L category.", "enum": [ "revenue", "cost_of_revenue", null ], "example": "revenue", "type": [ "string", "null" ] } }, "required": [ "period", "grouping", "line_category", "amount" ], "type": "object" }, "type": "array" }, "total": { "example": 23750.55, "type": "number" } }, "required": [ "report_type", "rows", "total" ], "type": "object" } } }, "description": "financial report returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid report type" }, "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 account" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Get Financial Report", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "/financial_reports/breakdown": { "get": { "description": "Returns the top entities behind one high-level financial report bucket and an aggregate remainder.", "operationId": "getFinancialReportBreakdown", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The owning account ID (a biz_ identifier).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "The high-level report bucket to explain.", "in": "query", "name": "bucket", "required": true, "schema": { "enum": [ "transfers", "payments", "card_spend", "withdrawals", "swaps" ], "type": "string" } }, { "description": "Whether to explain money received or money sent.", "in": "query", "name": "direction", "required": true, "schema": { "enum": [ "money_in", "money_out" ], "type": "string" } }, { "description": "The report currency to explain.", "in": "query", "name": "currency", "required": true, "schema": { "type": "string" } }, { "description": "Start of the report window as an ISO 8601 timestamp.", "in": "query", "name": "from_date", "required": true, "schema": { "type": "string" } }, { "description": "Exclusive end of the report window as an ISO 8601 timestamp.", "in": "query", "name": "to_date", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "activity_filters": { "properties": { "direction": { "enum": [ "money_in", "money_out" ], "example": "money_out", "type": "string" }, "line_types": { "items": { "example": "platform_balance_transfer_outgoing", "type": "string" }, "type": "array" } }, "required": [ "line_types", "direction" ], "type": "object" }, "bucket": { "enum": [ "transfers", "payments", "card_spend", "withdrawals", "swaps" ], "example": "transfers", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "direction": { "enum": [ "money_in", "money_out" ], "example": "money_out", "type": "string" }, "items": { "items": { "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "image_url": { "type": [ "string", "null" ] }, "key": { "description": "An opaque identifier for this grouping within the breakdown.", "type": "string" }, "name": { "type": "string" }, "object": { "enum": [ "user", "account", "merchant", "payout_destination", "balance" ], "example": "user", "type": "string" }, "resource_id": { "description": "The prefixed identifier of the represented Whop resource, when one exists.", "type": [ "string", "null" ] } }, "required": [ "key", "resource_id", "object", "name", "image_url", "amount" ], "type": "object" }, "maxItems": 5, "type": "array" }, "other_amount": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "bucket", "direction", "currency", "items", "other_amount", "activity_filters" ], "type": "object" } } }, "description": "breakdown returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid breakdown parameters" }, "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": "Get Financial Report Breakdown", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "profile_type", "required": false, "schema": { "$ref": "#/components/schemas/IdentityProfileKinds", "description": "Filter by profile type (individual or business)." }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/IdentityProfileStatuses", "description": "Filter by derived verification status." }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for ordering results, either ascending or descending." }, "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" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/InvoicesSortableColumns", "description": "The field to order results by, such as creation date or due date." }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`", "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. Individual items may be negative to represent a credit, as long as the sum is not negative and clears the currency's minimum charge.", "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. Negative values represent a credit or deduction, as long as the line items still total a chargeable amount.", "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": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": [ "boolean", "null" ] }, "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. Individual items may be negative to represent a credit, as long as the sum is not negative and clears the currency's minimum charge.", "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. Negative values represent a credit or deduction, as long as the line items still total a chargeable amount.", "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": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": [ "boolean", "null" ] }, "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" }, "429": { "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": "Too many requests" }, "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", "member:email:read", "member:basic:read", "payment:basic:read" ] } ], "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" }, "429": { "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": "Too many requests" }, "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`\n - `member:email:read`\n - `member:basic:read`\n - `payment: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" }, "429": { "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": "Too many requests" }, "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", "member:email:read", "member:basic:read", "payment: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`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`", "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. When provided, the sum of (quantity * unit_price) for all items must equal the plan price. Individual items may be negative to represent a credit, as long as the sum is not negative and clears the currency's minimum charge. Pass an empty list to remove the breakdown.", "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. Negative values represent a credit or deduction, as long as the line items still total a chargeable amount.", "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": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "type": [ "boolean", "null" ] }, "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" }, "429": { "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": "Too many requests" }, "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", "member:email:read", "member:basic:read", "payment:basic:read" ] } ], "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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}/resend": { "post": { "description": "Resend the notification email for an existing invoice to the customer.\n\nRequired permissions:\n - `invoice:update`", "operationId": "resendInvoice", "parameters": [ { "description": "The unique identifier of the invoice to resend.", "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" }, "429": { "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": "Too many requests" }, "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": "Resend 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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/media/generate": { "post": { "description": "Starts an AI media generation job billed from the account's balance. Generation is asynchronous — poll `GET /media/{id}` until the asset is `ready`, then use `file.id` anywhere attachments are accepted.", "operationId": "generateMediaAsset", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`. Defaults to the account the API key belongs to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "duration_seconds": { "description": "Video length in seconds. Video only; defaults to 5.", "enum": [ 5, 10, 15 ], "example": 5, "type": "integer" }, "prompt": { "description": "What to generate. Up to 2,000 characters.", "example": "A 9:16 product showcase of a cordless power scrubber", "type": "string" }, "reference_media": { "description": "Optional reference image file IDs (`file_` prefixed), up to 4. For video, a single reference seeds the opening frame; multiple references guide subject and style instead.", "items": { "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "resolution": { "description": "Video resolution. Video only; defaults to `1080p`. `1080p` is not supported by Seedance 2.0 Fast or Mini; `4k` is only supported by Seedance 2.0.", "enum": [ "480p", "720p", "1080p", "4k" ], "example": "1080p", "type": "string" }, "type": { "description": "The kind of media to generate.", "enum": [ "video", "image" ], "example": "video", "type": "string" } }, "required": [ "type", "prompt" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "description": "Generation started." }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "message": { "example": "duration_seconds is only valid for video generations", "type": "string" }, "type": { "example": "bad_request", "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid generation parameters." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "deposit_url": { "description": "Hosted page where the account can deposit funds before retrying.", "example": "https://whop.com/deposit/biz_xxxxxxxxxxxxxx/", "type": "string" }, "message": { "example": "Insufficient balance to fund this generation. Deposit funds and retry.", "type": "string" }, "type": { "enum": [ "payment_required" ], "example": "payment_required", "type": "string" } }, "required": [ "type", "message", "deposit_url" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Insufficient balance." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Missing the media:generate scope." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "media:generate" ] } ], "summary": "Generate Media Asset", "tags": [ "Media" ] }, "x-whop-surface": "native" }, "/media/{id}": { "get": { "description": "Retrieves a media asset by ID. Poll this while the asset is `processing`.", "operationId": "retrieveMediaAsset", "parameters": [ { "description": "Media asset ID, prefixed `media_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "description": "Media asset retrieved." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Unknown media asset, including generation jobs not created through this API." } }, "security": [ { "bearerAuth": [ "media:read" ] } ], "summary": "Retrieve Media Asset", "tags": [ "Media" ] }, "x-whop-surface": "native" }, "/members": { "get": { "description": "Lists the members of an account. A member is one buyer's relationship with the account, regardless of how many memberships they hold.", "operationId": "listMembers", "parameters": [ { "description": "The account to list members for (`biz_` tag). Defaults to the account the credential acts as.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by what the member can reach on the account.", "in": "query", "name": "access_level", "required": false, "schema": { "enum": [ "no_access", "admin", "customer" ], "type": "string" } }, { "description": "Filter by whether the member is still part of the account.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "joined", "left" ], "type": "string" } }, { "description": "Search members by name or username. An exact email address also matches when the credential holds the member:email:read scope.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only members who joined after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only members who joined before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "joined_at", "last_accessed_at", "usd_total_spent" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of members to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of members to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Member" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "members listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid access_level filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the member-read scope" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Members", "tags": [ "Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/members/{id}": { "get": { "description": "Retrieves a member by ID. Accessible to the account and to the member's own user.", "operationId": "retrieveMember", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } }, "description": "member phone falls back to the stamped checkout-collected number" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks access to the member's account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown member" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "Retrieve Member", "tags": [ "Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Member ID (`mber_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/members/{id}/logs": { "get": { "description": "Lists activity for a member and all of their non-drafted memberships, most recent first.", "operationId": "listMemberLogs", "parameters": [ { "description": "Number of log entries to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of log entries to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "action": { "example": "Membership activated", "type": [ "string", "null" ] }, "actor": { "properties": { "id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "action", "created_at", "actor" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "member logs listed" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks access to the member's account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown member" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Member Logs", "tags": [ "Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Member ID (`mber_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/memberships": { "get": { "description": "Lists every membership the caller can read: an account API key its account's; a user credential their own plus those of every account they manage. `account_id` and `user_id` only narrow that list — values outside the caller's reach return fewer results, not an error.", "operationId": "listMemberships", "parameters": [ { "description": "Narrow to one account (`biz_` tag). With read access to the account this lists all of its memberships; without, only the caller's own memberships in it.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Narrow to one user's memberships (`user_` tag, or `me` for the caller). A user outside the caller's visible set returns an empty list.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by billing state. `canceling` matches active memberships set to cancel at period end; `paused` matches memberships with payment collection paused.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "trialing", "past_due", "completed", "canceled", "expired", "canceling", "paused" ], "type": "string" } }, { "description": "Filter to memberships of this product (`prod_` tag). Repeat as product_ids[] for several.", "in": "query", "name": "product_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to memberships of this plan (`plan_` tag). Repeat as plan_ids[] for several.", "in": "query", "name": "plan_id", "required": false, "schema": { "type": "string" } }, { "description": "Only memberships created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only memberships created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of memberships to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of memberships to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Membership" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "memberships listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account_id" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Memberships", "tags": [ "Memberships" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/memberships/invite": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Sends an email inviting one recipient to join the account through a free plan. Identify the recipient by exactly one of `user_id` or `email`. The invitation is bound to that recipient; after signing in, accepting it immediately grants the membership without checkout. This Experimental endpoint is available only to accounts enabled for membership invitations.", "operationId": "inviteMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "plan_id": { "description": "Free plan whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "Recipient user ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_id", "user_id" ], "title": "InviteMembershipByUser", "type": "object" }, { "properties": { "email": { "description": "Recipient email address.", "example": "marcus@shinetime.example", "format": "email", "type": "string" }, "plan_id": { "description": "Free plan whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_id", "email" ], "title": "InviteMembershipByEmail", "type": "object" } ], "properties": { "email": { "description": "Recipient email address. Mutually exclusive with `user_id`.", "example": "marcus@shinetime.example", "format": "email", "type": "string" }, "plan_id": { "description": "Free plan whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "Recipient user ID, prefixed `user_`. Mutually exclusive with `email`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_id" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "invitation_sent": { "example": true, "type": "boolean" } }, "required": [ "invitation_sent" ], "type": "object" } } }, "description": "invitation accepted for delivery" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid recipient" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the create scope or account is not enabled" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown plan" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:create" ] } ], "summary": "Invite to a Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}": { "get": { "description": "Retrieves a membership by ID or license key. Accessible to the account and to the membership's own user.", "operationId": "retrieveMembership", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership retrieved with its recorded phone number" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks access to the membership" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown membership" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "Retrieve Membership", "tags": [ "Memberships" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag), or a software license key.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a membership: merge metadata key-value pairs, or toggle `cancel_at_period_end` — `true` schedules the cancellation for the end of the current billing period, `false` reverses a pending one.", "operationId": "updateMembership", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cancel_at_period_end": { "description": "`true` cancels at the end of the current billing period (the customer keeps access until then); `false` reverses a pending cancellation.", "example": true, "type": "boolean" }, "metadata": { "description": "Key-value pairs to merge into the membership's metadata. Pass an empty object to clear it.", "example": { "seat": "42" }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no updatable fields given" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" } }, "security": [ { "bearerAuth": [ "member:manage" ] }, { "bearerAuth": [ "membership:cancel" ] } ], "summary": "Update Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/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" }, "429": { "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": "Too many requests" }, "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": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a membership. Pass `cancel_at_period_end: true` to stop auto-renewal and keep access until the current billing period ends. Omit it (or pass `false`) to revoke access immediately. Buyers cannot cancel buy-now-pay-later (`splitit`, `sezzle`) or non-trial split-pay memberships.", "operationId": "cancelMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cancel_at_period_end": { "description": "`true` stops auto-renewal and keeps access until the current billing period ends. Omit or `false` revokes access immediately.", "example": true, "type": "boolean" }, "reason": { "description": "Free-form note recording why the membership was canceled.", "example": "chargeback risk", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership canceled" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the cancel scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown membership" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:cancel" ] }, { "bearerAuth": [ "member:manage" ] } ], "summary": "Cancel Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/extend": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Adds free days to a membership, extending its current billing period, expiration date, or trial depending on the plan type.", "operationId": "extendMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "days": { "description": "Number of free days to add (1-1095).", "example": 7, "minimum": 1, "type": "integer" } }, "required": [ "days" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership extended" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "days is not a positive integer" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Extend Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses a membership's recurring payment collection. The customer keeps access but is not charged until the membership is resumed.", "operationId": "pauseMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "until": { "description": "ISO 8601 time to automatically resume payment collection. Must be in the future; only supported for memberships billed by Whop.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership paused" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "until on a membership not billed by Whop" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Pause Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/resume": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes a previously paused membership's recurring payment collection. Billing resumes on the next cycle.", "operationId": "resumeMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership resumed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "membership cannot be resumed" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Resume Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/resync_access": { "post": { "description": "Re-run access fulfillment for a membership. Recomputes the member's content access on Whop, re-validates their Discord link (re-adding them to the server and re-assigning roles if needed), and re-fulfills TradingView indicator access. Telegram access is invite-based and cannot be resynced here. The outcome is written to the membership's logs.\n\nRequired permissions:\n - `membership:resync_access`\n - `member:email:read`\n - `member:basic:read`", "operationId": "resyncAccessMembership", "parameters": [ { "description": "The unique identifier of the membership to resync access for.", "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" }, "429": { "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": "Too many requests" }, "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:resync_access", "member:email:read", "member:basic:read" ] } ], "summary": "Resync access membership", "tags": [ "Memberships" ], "x-group-title": "CRM" } }, "/memberships/{id}/transfer": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Creates a one-use transfer URL for a membership. Opening the URL while logged into a different Whop account claims the membership onto that account. The membership's buyer can generate a link for their own membership with `membership:transfer` when the product allows transfers and the membership is `trialing`, `active`, or `completed`. An account credential with `membership:update` bypasses both restrictions.", "operationId": "transferMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "url": { "description": "One-use URL the destination account opens to claim the membership.", "example": "https://whop.com/activate", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "description": "transfer URL created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "membership is not transferable in its current state" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the transfer scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown membership" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:transfer" ] }, { "bearerAuth": [ "membership:update" ] } ], "summary": "Transfer Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/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" }, "429": { "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": "Too many requests" }, "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 (one of):\n - `chat:read`\n - `dms:read`\n - `support_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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for messages by creation time. Use 'asc' for oldest first or 'desc' for newest first." }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_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 (one of):\n - `chat:message:create`\n - `dms:message:manage`\n - `livestream:chat:write`\n - `support_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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:message:manage" ] }, { "bearerAuth": [ "livestream:chat:write" ] }, { "bearerAuth": [ "support_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 (one of):\n - `chat:message:create` and `chat:read`\n - `dms:message:manage` and `dms:read`\n - `livestream:chat:write` and `livestream:chat:read`\n - `support_chat:message:create` and `support_chat:read`", "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" }, "429": { "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": "Too many requests" }, "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", "chat:read" ] }, { "bearerAuth": [ "dms:message:manage", "dms:read" ] }, { "bearerAuth": [ "livestream:chat:write", "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:message:create", "support_chat:read" ] } ], "summary": "Delete message", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing message.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `livestream:chat:read`\n - `support_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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_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.\n\nRequired permissions (one of):\n - `chat:message:create`\n - `dms:message:manage`\n - `livestream:chat:write`\n - `support_chat:message:create`", "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:message:manage" ] }, { "bearerAuth": [ "livestream:chat:write" ] }, { "bearerAuth": [ "support_chat:message:create" ] } ], "summary": "Update message", "tags": [ "Messages" ], "x-group-title": "Engagement" } }, "/notifications": { "get": { "description": "Lists the authenticated user's notifications, newest first. Requires a user credential — an account API key has no notification feed. Without filters the feed spans every experience the user belongs to plus the teams they are a member of.", "operationId": "listNotifications", "parameters": [ { "description": "Only return notifications created since the user last viewed their source.", "in": "query", "name": "unread", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return notifications from this experience (`exp_` tag).", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return team notifications for this account (`biz_` tag).", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return notifications that mention the user directly.", "in": "query", "name": "mentions", "required": false, "schema": { "type": "boolean" } }, { "description": "The number of notifications to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor (a notification `id` from a previous page); returns notifications older than it.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Notification" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "ntfr_xxxxxxxxxxxxxx:xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "ntfr_xxxxxxxxxxxxxx:xxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "notifications listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid cursor" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account API key instead of a user credential" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Notifications", "tags": [ "Notifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Queues a notification to every user of an experience or to an account's team, processed asynchronously. Every send is attributed to an app: use an app API key, or a credential acting on behalf of an app. Narrow the audience with `user_ids` to send a mention.", "operationId": "sendNotification", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account whose team members receive the notification (`biz_` tag). Exactly one of `experience_id` or `account_id` is required.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "content": { "description": "Main body text of the notification.", "example": "Drop off at 4180 Burnet Rd. Plan on two days for the full coating.", "type": "string" }, "experience_id": { "description": "Experience whose users receive the notification (`exp_` tag). Exactly one of `experience_id` or `account_id` is required.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "icon_user_id": { "description": "User whose profile picture is used as the notification icon. Defaults to the experience or account avatar.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "rest_path": { "description": "Path segment appended to the generated deep link that opens your app, for example `/settings/billing`.", "example": "/bookings/upcoming", "type": [ "string", "null" ] }, "subtitle": { "description": "Optional secondary line displayed below the title.", "example": "Tuesday 9:00 AM, Bay 2", "type": [ "string", "null" ] }, "title": { "description": "Headline text of the notification.", "example": "Your ceramic coating is booked", "type": "string" }, "user_ids": { "description": "Optional `user_` tags narrowing the audience. When provided, only these users are notified (as a mention), provided they are in the targeted experience or account.", "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "title", "content" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "notification queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "both targets provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential is not attributed to an app" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [ "notification:create" ] } ], "summary": "Send Notification", "tags": [ "Notifications" ] }, "x-whop-surface": "native" }, "/notifications/badges": { "get": { "description": "Lists the authenticated user's per-experience unread badge state. Requires a user credential. Returns one row per experience the user belongs to (or per requested experience).", "operationId": "listNotificationBadges", "parameters": [ { "description": "Only return badges for these experiences (`exp_` tags).", "in": "query", "name": "experience_ids", "required": false, "schema": { "items": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "The client's last fetched-at ISO 8601 timestamp, used to partially refresh badges after a websocket message.", "in": "query", "name": "last_fetched_at", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationBadge" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "badges listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account API key instead of a user credential" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Notification Badges", "tags": [ "Notifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/notifications/mark_read": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Marks the authenticated user's notifications as read: one experience's (`experience_id`) or everything (`all: true`) — exactly one of the two. Requires a user credential. Responds with the refreshed badge rows for the affected scope.", "operationId": "markNotificationsRead", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "all": { "description": "Pass `true` to mark every notification read. Exactly one of `experience_id` or `all` is required.", "example": true, "type": "boolean" }, "experience_id": { "description": "Experience to mark read (`exp_` tag). Exactly one of `experience_id` or `all` is required.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationBadge" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "notifications marked read" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither or both selectors provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account API key instead of a user credential" }, "404": { "$ref": "#/components/responses/NotFound", "description": "experience does not exist" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "user:notifications:update" ] } ], "summary": "Mark Notifications Read", "tags": [ "Notifications" ] }, "x-whop-surface": "native" }, "/notifications/topics": { "get": { "description": "Lists the platform's visible notification topics — the categories users can set notification preferences on. App-created topics are internal and not returned.", "operationId": "listNotificationTopics", "parameters": [ { "description": "Only return topics of this scope: `user` (member notifications) or `account_team` (team notifications).", "in": "query", "name": "topic_type", "required": false, "schema": { "enum": [ "user", "account_team" ], "type": "string" } }, { "description": "The number of topics to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns topics after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationTopic" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "notification topics listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid topic_type" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Notification Topics", "tags": [ "Notifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/notifications/{id}": { "get": { "description": "Retrieves a single notification by id — either an `id` returned by List Notifications, or the ephemeral id delivered with a push/websocket event. Requires a user credential.", "operationId": "retrieveNotification", "parameters": [ { "description": "A notification `id` from List Notifications, or the id delivered with a push/websocket event.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } }, "description": "notification found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "notification expired or not visible to the user" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "Retrieve Notification", "tags": [ "Notifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Enrolls the calling user in the Whop partner program, making their partner businesses eligible for earnings. Idempotent — enrolling again keeps the original enrollment time.", "operationId": "createReferralPartner", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "referral_link": { "description": "The caller's referral link — businesses that sign up through it are attributed to the caller.", "example": "https://whop.com/network/", "type": "string" }, "whop_partner_enabled_at": { "description": "When the caller became a Whop partner.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "whop_partner_enabled_at", "referral_link" ], "type": "object" } } }, "description": "enrolled" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the partner-create scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "partner:create" ] } ], "summary": "Enroll as a Whop partner", "tags": [ "Partners" ] }, "x-whop-surface": "native" }, "/partners/businesses": { "get": { "description": "Lists the businesses the authenticated user referred onto Whop, most recent first.", "operationId": "listPartnerBusinesses", "parameters": [ { "description": "Filter by referral status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "removed" ], "type": "string" } }, { "description": "When true, only businesses with pending or completed earnings paid to the caller.", "in": "query", "name": "has_earnings", "required": false, "schema": { "type": "boolean" } }, { "description": "Number of partner businesses to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of partner businesses to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort partner businesses by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "referral_started_at", "referral_expires_at", "payout_percentage", "volume_usd", "earnings_usd" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return partner businesses created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return partner businesses created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Filter to referrals attributed to this user. For first-tier referrals, this is the referred account owner; for second-tier referrals, this is the partner you recruited.", "in": "query", "name": "referred_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by the referred user's exact username. Ignored when `referred_user_id` is present.", "in": "query", "name": "referred_username", "required": false, "schema": { "type": "string" } }, { "description": "Filter to referrals from a single tier: first, second, or blueprint.", "in": "query", "name": "tier", "required": false, "schema": { "enum": [ "first", "second", "blueprint" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account": { "description": "Referred account.", "properties": { "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "blueprint_partner": { "description": "The partner whose blueprint the business deployed. Null unless this is a blueprint referral.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "earnings_usd": { "properties": { "completed": { "description": "Commission already paid out, in USD.", "example": "3.00", "type": "string" }, "pending": { "description": "Commission scheduled but not yet paid, in USD.", "example": "1.00", "type": "string" }, "total": { "description": "Pending + completed commission, in USD.", "example": "4.00", "type": "string" } }, "required": [ "total", "pending", "completed" ], "type": "object" }, "first_tier_partner": { "description": "The partner who referred the business owner onto Whop (first tier). Null if there is no active first-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "id": { "description": "Partner business ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" }, "my_partner_tier": { "description": "Which tier the caller earns on for this business: `first` (they referred the owner), `second` (they referred the first-tier partner), or `blueprint` (the business deployed a site from their blueprint).", "enum": [ "first", "second", "blueprint" ], "example": "first", "type": "string" }, "object": { "enum": [ "partner_business" ], "example": "partner_business", "type": "string" }, "owner": { "description": "The owner of the referred business.", "properties": { "email": { "description": "The business owner's email address, so a partner can follow up on a referral they made. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture", "email" ], "type": [ "object", "null" ] }, "payout_percentages": { "description": "The referrer's commission rate for each income source, expressed as a fraction (0.3 = 30%).", "properties": { "ad_spend": { "description": "Share of the referred business's Whop Ads spend.", "example": 0.015, "format": "float", "type": [ "number", "null" ] }, "card_interchange": { "description": "Share of Whop's profit from card interchange.", "example": 0.2, "format": "float", "type": [ "number", "null" ] }, "sales": { "description": "Share of Whop's profit from product sales.", "example": 0.3, "format": "float", "type": "number" }, "transfer": { "description": "Share of Whop's profit from platform balance transfers.", "example": 0.25, "format": "float", "type": [ "number", "null" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange" ], "type": "object" }, "referral_expires_at": { "description": "When the referral expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referral_started_at": { "description": "When the referral became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "second_tier_partner": { "description": "The second-tier partner who earns on this business (referred the first-tier partner). Null if there is no active second-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "status": { "description": "Current referral status.", "enum": [ "active", "removed" ], "example": "active", "type": "string" }, "volume_usd": { "properties": { "attributed": { "description": "Credited GMV (awaiting_settlement + settled); excludes canceled and reversed, in USD.", "example": "40.00", "type": "string" }, "awaiting_settlement": { "description": "GMV awaiting settlement (commission not yet computed), in USD.", "example": "0.00", "type": "string" }, "settled": { "description": "GMV of pending + completed payments, in USD.", "example": "40.00", "type": "string" } }, "required": [ "attributed", "awaiting_settlement", "settled" ], "type": "object" } }, "required": [ "object", "id", "account", "owner", "first_tier_partner", "second_tier_partner", "blueprint_partner", "my_partner_tier", "status", "payout_percentages", "referral_started_at", "referral_expires_at", "created_at", "volume_usd", "earnings_usd" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "partner businesses listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid sort field" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the referral-read scope" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] } ], "summary": "List referred businesses", "tags": [ "Partners" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners/businesses/{id}": { "get": { "description": "Retrieves a single referred business and its referral terms.", "operationId": "retrievePartnerBusiness", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "description": "Referred account.", "properties": { "capabilities": { "$ref": "#/components/schemas/AccountCapabilities", "nullable": true }, "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "recommended_actions": { "description": "Optional actions that unlock capabilities or grow the referred account.", "items": { "$ref": "#/components/schemas/AccountRecommendedAction" }, "type": [ "array", "null" ] }, "required_actions": { "description": "Actions the referred account owner must take to unblock capabilities.", "items": { "$ref": "#/components/schemas/AccountRequiredAction" }, "type": [ "array", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route", "capabilities", "required_actions", "recommended_actions" ], "type": [ "object", "null" ] }, "blueprint_partner": { "description": "The partner whose blueprint the business deployed. Null unless this is a blueprint referral.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "earnings_usd": { "properties": { "completed": { "description": "Commission already paid out, in USD.", "example": "0.00", "type": "string" }, "pending": { "description": "Commission scheduled but not yet paid, in USD.", "example": "0.00", "type": "string" }, "total": { "description": "Pending + completed commission, in USD.", "example": "0.00", "type": "string" } }, "required": [ "total", "pending", "completed" ], "type": "object" }, "first_tier_partner": { "description": "The partner who referred the business owner onto Whop (first tier). Null if there is no active first-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "id": { "description": "Partner business ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" }, "my_partner_tier": { "description": "Which tier the caller earns on for this business: `first` (they referred the owner), `second` (they referred the first-tier partner), or `blueprint` (the business deployed a site from their blueprint).", "enum": [ "first", "second", "blueprint" ], "example": "blueprint", "type": "string" }, "object": { "enum": [ "partner_business" ], "example": "partner_business", "type": "string" }, "owner": { "description": "The owner of the referred business.", "properties": { "email": { "description": "The business owner's email address, so a partner can follow up on a referral they made. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "tanyacole", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture", "email" ], "type": [ "object", "null" ] }, "payout_percentages": { "description": "The referrer's commission rate for each income source, expressed as a fraction (0.3 = 30%).", "properties": { "ad_spend": { "description": "Share of the referred business's Whop Ads spend.", "example": 0.015, "format": "float", "type": [ "number", "null" ] }, "card_interchange": { "description": "Share of Whop's profit from card interchange.", "example": 0.2, "format": "float", "type": [ "number", "null" ] }, "sales": { "description": "Share of Whop's profit from product sales.", "example": 0.3, "format": "float", "type": "number" }, "transfer": { "description": "Share of Whop's profit from platform balance transfers.", "example": 0.25, "format": "float", "type": [ "number", "null" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange" ], "type": "object" }, "referral_expires_at": { "description": "When the referral expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referral_started_at": { "description": "When the referral became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "second_tier_partner": { "description": "The second-tier partner who earns on this business (referred the first-tier partner). Null if there is no active second-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "status": { "description": "Current referral status.", "enum": [ "active", "removed" ], "example": "active", "type": "string" }, "volume_usd": { "properties": { "attributed": { "description": "Credited GMV (awaiting_settlement + settled); excludes canceled and reversed, in USD.", "example": "0.00", "type": "string" }, "awaiting_settlement": { "description": "GMV awaiting settlement (commission not yet computed), in USD.", "example": "0.00", "type": "string" }, "settled": { "description": "GMV of pending + completed payments, in USD.", "example": "0.00", "type": "string" } }, "required": [ "attributed", "awaiting_settlement", "settled" ], "type": "object" } }, "required": [ "object", "id", "account", "owner", "first_tier_partner", "second_tier_partner", "blueprint_partner", "my_partner_tier", "status", "payout_percentages", "referral_started_at", "referral_expires_at", "created_at", "volume_usd", "earnings_usd" ], "type": "object" } } }, "description": "partner business retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no such partner business is visible to the credential" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] } ], "summary": "Retrieve a referred business", "tags": [ "Partners" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/partners/businesses/{id}/earnings": { "get": { "description": "Lists the earnings Whop pays out for one referred business's activity, most recent first.", "operationId": "listPartnerBusinessEarnings", "parameters": [ { "description": "Filter by earning status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "awaiting_settlement", "pending", "completed", "canceled", "reversed" ], "type": "string" } }, { "description": "Filter to earnings from these income sources. Repeat the parameter for each one (income_source=sales&income_source=ad_spend).", "explode": true, "in": "query", "name": "income_source", "required": false, "schema": { "items": { "enum": [ "sales", "ad_spend", "transfer", "card_interchange" ], "example": "sales", "type": "string" }, "type": "array" }, "style": "form" }, { "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort earnings by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "commission_amount", "transaction_amount", "payout_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return earnings created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return earnings created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account": { "description": "Referred account.", "properties": { "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "cancelation_reason": { "description": "Why the earning was canceled or reversed, if applicable.", "example": "payment_refunded", "type": [ "string", "null" ] }, "commission_amount_usd": { "description": "What the referrer earns, in USD. Null until the earning settles.", "example": "1.00", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "financial_activity": { "description": "Income and cost lines behind this earning's commission. Null for earnings settled before this data was recorded.", "items": { "properties": { "amount": { "description": "Line amount in its native currency.", "example": "3.00", "type": "string" }, "amount_usd": { "description": "Line amount in USD.", "example": "3.00", "type": "string" }, "category": { "description": "Fee or cost category of the line.", "example": "whop_processing_fee", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Currency of the native amount.", "example": "usd", "type": "string" }, "type": { "description": "Whether the line is income Whop collected or a cost Whop paid.", "enum": [ "income", "expense" ], "example": "income", "type": "string" } }, "required": [ "type", "category", "currency", "amount", "amount_usd", "created_at" ], "type": "object" }, "type": [ "array", "null" ] }, "id": { "example": "afpy_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "income_source": { "description": "Which income source the commission is on: product-sales gross profit, Whop Ads spend billed to the business, platform balance transfer fees, or Whop Card interchange.", "enum": [ "sales", "ad_spend", "transfer", "card_interchange" ], "example": "sales", "type": "string" }, "object": { "enum": [ "partner_business_earning" ], "example": "partner_business_earning", "type": "string" }, "payout_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "payout_percentage": { "description": "The referrer's share of Whop's gross profit, as a fraction (0.3 = 30%). Null until the earning settles.", "example": 0.04, "format": "float", "type": [ "number", "null" ] }, "product": { "properties": { "id": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "route": { "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "title": { "example": "Ceramic Coating Package", "type": "string" } }, "required": [ "id", "title", "route" ], "type": [ "object", "null" ] }, "resource": { "anyOf": [ { "properties": { "alternative_payment_method": { "properties": { "image_url": { "example": "https://content.whop.com/core/pm_cashapp.svg", "type": [ "string", "null" ] }, "name": { "example": "Cash App", "type": "string" } }, "required": [ "name", "image_url" ], "type": [ "object", "null" ] }, "brand": { "example": "visa", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "example": "4242", "type": [ "string", "null" ] }, "object": { "enum": [ "receipt" ], "example": "receipt", "type": "string" }, "payment_method_type": { "example": "card", "type": [ "string", "null" ] }, "processor": { "example": "stripe", "type": [ "string", "null" ] } }, "required": [ "object", "id", "currency", "payment_method_type", "processor", "brand", "last4", "created_at", "alternative_payment_method" ], "type": [ "object", "null" ] }, { "properties": { "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "transfer" ], "example": "transfer", "type": "string" } }, "required": [ "object", "id", "currency", "created_at" ], "type": "object" }, { "properties": { "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "id": { "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "merchant_name": { "example": "Austin Detail Supply", "type": [ "string", "null" ] }, "object": { "enum": [ "card_transaction" ], "example": "card_transaction", "type": "string" } }, "required": [ "object", "id", "currency", "merchant_name", "created_at" ], "type": "object" }, { "type": "null" } ], "description": "The resource that generated the earning: the customer payment receipt for sales and ad spend earnings, the balance transfer for transfer earnings, or the card transaction for card interchange earnings." }, "second_tier": { "description": "Whether this earning is a second-tier (grandparent) commission.", "example": false, "type": "boolean" }, "status": { "description": "Current status of the earning.", "enum": [ "awaiting_settlement", "pending", "completed", "canceled", "reversed" ], "example": "pending", "type": "string" }, "transaction_amount_usd": { "description": "The underlying transaction amount the commission's income comes from, in USD.", "example": "10.00", "type": "string" } }, "required": [ "object", "id", "account", "product", "status", "second_tier", "income_source", "transaction_amount_usd", "payout_percentage", "commission_amount_usd", "financial_activity", "cancelation_reason", "created_at", "payout_at", "resource" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "earnings listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid sort direction" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] } ], "summary": "List referred business earnings", "tags": [ "Partners" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/partners/leaderboard": { "get": { "description": "Ranks referrers by partner business earnings — all-time by default, or over the current day, month, year, or trailing 30 days. Authentication is optional: authenticated callers also get their own standing, anonymous callers get the rankings alone.", "operationId": "retrievePartnerLeaderboard", "parameters": [ { "description": "Time window for the rankings. `day`, `month`, and `year` count earnings since the start of the current calendar day, month, or year; `last_30_days` counts earnings over the trailing 30 days; `all_time` ranks lifetime earnings.", "in": "query", "name": "period", "required": false, "schema": { "default": "all_time", "enum": [ "day", "month", "year", "last_30_days", "all_time" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "leaders": { "description": "The top referrers by total earnings, best first.", "items": { "properties": { "first_referral_started_at": { "description": "When the referrer's earliest partner business became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "rank": { "description": "1-based leaderboard position.", "example": 1, "type": "integer" }, "total_earnings_usd": { "description": "The referrer's pending + completed earnings across all referred businesses, in USD.", "example": "100.00", "type": "string" }, "total_volume_usd": { "description": "Credited GMV across all the referrer's referred businesses, in USD.", "example": "0.00", "type": "string" }, "user": { "description": "The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.", "properties": { "city": { "description": "The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "US", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`. Present only on the caller's own entry.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name. Present only on the caller's own entry.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture. Present only on the caller's own entry.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username. Present only on the caller's own entry.", "example": "marcuswebb", "type": "string" } }, "required": [ "country", "city" ], "type": [ "object", "null" ] } }, "required": [ "rank", "total_earnings_usd", "total_volume_usd", "first_referral_started_at", "user" ], "type": "object" }, "maxItems": 10, "type": "array" }, "me": { "description": "The caller's own standing; null when the caller has no referral earnings.", "properties": { "first_referral_started_at": { "description": "When the referrer's earliest partner business became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "rank": { "description": "1-based leaderboard position.", "example": 2, "type": "integer" }, "total_earnings_usd": { "description": "The referrer's pending + completed earnings across all referred businesses, in USD.", "example": "4.00", "type": "string" }, "total_volume_usd": { "description": "Credited GMV across all the referrer's referred businesses, in USD.", "example": "40.00", "type": "string" }, "user": { "description": "The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.", "properties": { "city": { "description": "The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "US", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`. Present only on the caller's own entry.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name. Present only on the caller's own entry.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture. Present only on the caller's own entry.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username. Present only on the caller's own entry.", "example": "marcuswebb", "type": "string" } }, "required": [ "country", "city" ], "type": [ "object", "null" ] } }, "required": [ "rank", "total_earnings_usd", "total_volume_usd", "first_referral_started_at", "user" ], "type": [ "object", "null" ] } }, "required": [ "leaders", "me" ], "type": "object" } } }, "description": "caller has no referral earnings" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid period" } }, "security": [ {}, { "bearerAuth": [ "partner:basic:read" ] } ], "summary": "Retrieve the leaderboard", "tags": [ "Partners" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners/referred_users": { "get": { "description": "Lists the users the caller referred onto Whop (newest first), each with the second-tier earnings the caller has made from that user's businesses.", "operationId": "listReferredUsers", "parameters": [ { "description": "When true, only referred users who brought at least one business onto Whop.", "in": "query", "name": "has_businesses", "required": false, "schema": { "type": "boolean" } }, { "description": "When true, only referred users with at least one business that has generated earnings.", "in": "query", "name": "has_earning_businesses", "required": false, "schema": { "type": "boolean" } }, { "description": "Number of referred users to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of referred users to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "total_earnings_usd": { "example": "10.00", "type": "string" }, "total_volume_usd": { "example": "100.00", "type": "string" }, "user": { "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "example": "US", "type": [ "string", "null" ] }, "email": { "description": "The referred user's email address, so a partner can follow up with someone they brought onto Whop. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "example": "Tanya Cole", "type": [ "string", "null" ] }, "profile_picture": { "properties": { "url": { "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] } }, "type": "object" }, "username": { "example": "tanyacole", "type": "string" } }, "required": [ "id", "username", "email" ], "type": "object" } }, "required": [ "total_earnings_usd", "total_volume_usd", "user" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "referred users listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] } ], "summary": "List the users the caller referred", "tags": [ "Partners" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/payment_method_domains": { "get": { "description": "Lists payment method domains. Without `account_id`, returns the caller's own domains and those of every connected account.", "operationId": "listPaymentMethodDomains", "parameters": [ { "description": "Only domains registered for this account (`biz_` tag). Defaults to the caller's account plus its connected accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only the domain with this exact hostname.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Only domains with this verification status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "verified" ], "type": "string" } }, { "description": "Only domains registered with this wallet provider.", "in": "query", "name": "provider", "required": false, "schema": { "enum": [ "apple" ], "type": "string" } }, { "description": "Only domains created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only domains created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of domains to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of domains to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentMethodDomain" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payment method domains listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "List Payment Method Domains", "tags": [ "Payment Method Domains" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Registers a hostname with the wallet provider and attempts verification inline. Returns `verified` when the provider fetched the domain-association file (for Apple Pay, `/.well-known/apple-developer-merchantid-domain-association`), or `pending` when it could not — host the file, then retry with the verify endpoint.", "operationId": "createPaymentMethodDomain", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to register the domain for (`biz_` tag). Defaults to the caller's account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "hostname": { "description": "Hostname to register (e.g. `checkout.shinetime.example`).", "example": "pending.shinetime.example", "type": "string" } }, "required": [ "hostname" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDomain" } } }, "description": "domain registered as pending when verification fails" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "domain already verified" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Create Payment Method Domain", "tags": [ "Payment Method Domains" ] }, "x-whop-surface": "native" }, "/payment_method_domains/{id}": { "delete": { "description": "Unregisters a payment method domain so its wallet payment methods stop rendering there.", "operationId": "deletePaymentMethodDomain", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "pmd_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "payment method domain deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "domain not found" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Delete Payment Method Domain", "tags": [ "Payment Method Domains" ] }, "get": { "description": "Retrieves a payment method domain to check its verification status.", "operationId": "retrievePaymentMethodDomain", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDomain" } } }, "description": "payment method domain retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "domain not found" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Retrieve Payment Method Domain", "tags": [ "Payment Method Domains" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the payment method domain, prefixed `pmd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payment_method_domains/{id}/verify": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the payment method domain, prefixed `pmd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-attempts provider verification of a pending domain once the association file is hosted. Fails with a `bad_request` explaining what to fix; verifying an already `verified` domain is a no-op.", "operationId": "verifyPaymentMethodDomain", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDomain" } } }, "description": "already verified domain is a no-op" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "verification failed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "domain not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Verify Payment Method Domain", "tags": [ "Payment Method Domains" ] }, "x-whop-surface": "native" }, "/payment_methods": { "get": { "description": "Returns a paginated list of payment methods for a member or company, or for the authenticated user when neither is given, 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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member to list payment methods for. Omit this and company_id to list your own saved payment methods.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "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. Omit both to address your own saved payment methods.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for ordering results, either ascending or descending." }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "future_usage", "required": false, "schema": { "$ref": "#/components/schemas/FutureUsageTypes", "description": "Only return methods that can be charged this way after the buyer leaves. Every stored credential answers either usage today, so this narrows nothing — it used to drop the buyer's platform balance, which now lists on its own endpoint instead of here." }, "style": "form" }, { "explode": true, "in": "query", "name": "payment_method_types", "required": false, "schema": { "description": "Only return payment methods of these types. Pass the eligible `type` values from the payment method types catalogue so the list holds nothing the purchase cannot take. An empty list returns no payment methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "card_brands", "required": false, "schema": { "description": "Only return cards on these networks, such as the networks the seller accepts. Payment methods that are not cards are unaffected.", "items": { "$ref": "#/components/schemas/CardBrands" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "card_funding_types", "required": false, "schema": { "description": "Only return cards funded this way. A card whose funding could not be determined is excluded, and payment methods that are not cards are unaffected.", "items": { "$ref": "#/components/schemas/CardFundingTypes" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "has_payer_document", "required": false, "schema": { "description": "Filter cards by whether they carry the payer identity document their payment provider requires. Payment methods that are not cards are unaffected.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "expired", "required": false, "schema": { "description": "Filter by expiry. Only a card can expire, so `false` keeps every payment method that is not past its expiration month and `true` returns expired cards alone.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "broken", "required": false, "schema": { "description": "Filter by whether the stored credential has permanently stopped charging, such as a vault entry its provider closed.", "type": "boolean" }, "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" }, "429": { "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": "Too many requests" }, "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. Omit both to address your own saved payment methods.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "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. Omit both to address your own saved payment methods.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "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" }, "429": { "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": "Too many requests" }, "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. Addresses a member's wallet when member_id or company_id is given, otherwise your own.\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. Omit both to address your own saved payment methods.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "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. Omit both to address your own saved payment methods.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "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" }, "429": { "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": "Too many requests" }, "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`\n - `shipment: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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for ordering results, either ascending or descending." }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ReceiptV2Order", "description": "The field to order results by, such as creation date." }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "include_free", "required": false, "schema": { "description": "Whether to include payments with a zero amount. Defaults to false, so zero-amount payments are omitted unless you set this to true — a company whose sales are all free plans returns an empty list without it.", "type": "boolean" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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", "shipment:basic:read" ] } ], "summary": "List payments", "tags": [ "Payments" ], "x-group-title": "Payins" }, "post": { "description": "Charge a buyer on-session with a `confirmation_token` for the method they selected, or charge an existing member off-session using a stored payment method. You can provide an existing plan or create one inline. The endpoint returns a payment immediately, but processing continues asynchronously. Use webhooks to learn whether it succeeds or fails, and poll the payment's status endpoint for any step the buyer must complete.\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 - `shipment: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": { "capture": { "description": "Whether to capture the card payment immediately. Pass false to place an authorization hold that must be captured in full within five days.", "type": [ "boolean", "null" ] }, "company_id": { "description": "The ID of the company to create the payment for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "confirmation_token": { "description": "A confirmation token ID (ctok_) describing a payment method the buyer just supplied. Provide this INSTEAD of member_id and payment_method_id to charge a method that is not yet on file — the buyer is resolved from the token's billing email, or from `email`. The buyer may still have a step to complete (3DS, a redirect, linking a bank); poll the payment's status endpoint for what to do next.", "type": "string" }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the Whop user the payment belongs to. Ignored when the confirmation token was created by a signed-in buyer, and unless confirmation_token is provided.", "example": "buyer@example.com", "type": [ "string", "null" ] }, "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. Required unless confirmation_token is provided.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "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" }, "promo_code_id": { "description": "The ID of an active promo code to apply to this payment. The promo code must belong to the company and be valid for the plan being purchased. The plan must be attached to a product — promo codes are not eligible for one-off purchases.", "example": "promo_xxxxxxxxxxxx", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters. Editable until they return — see the payment's update endpoint. Ignored unless confirmation_token is provided.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [ "company_id", "plan", "confirmation_token" ], "title": "CreatePaymentInputWithPlanAndConfirmationToken", "type": "object" }, { "description": "Autogenerated input type of CreatePayment", "properties": { "capture": { "description": "Whether to capture the card payment immediately. Pass false to place an authorization hold that must be captured in full within five days.", "type": [ "boolean", "null" ] }, "company_id": { "description": "The ID of the company to create the payment for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the Whop user the payment belongs to. Ignored when the confirmation token was created by a signed-in buyer, and unless confirmation_token is provided.", "example": "buyer@example.com", "type": [ "string", "null" ] }, "member_id": { "description": "The ID of the member to create the payment for. Required unless confirmation_token is provided.", "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. Required unless confirmation_token is provided.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "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" }, "promo_code_id": { "description": "The ID of an active promo code to apply to this payment. The promo code must belong to the company and be valid for the plan being purchased. The plan must be attached to a product — promo codes are not eligible for one-off purchases.", "example": "promo_xxxxxxxxxxxx", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters. Editable until they return — see the payment's update endpoint. Ignored unless confirmation_token is provided.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [ "company_id", "plan", "member_id" ], "title": "CreatePaymentInputWithPlanAndMemberId", "type": "object" }, { "description": "Autogenerated input type of CreatePayment", "properties": { "capture": { "description": "Whether to capture the card payment immediately. Pass false to place an authorization hold that must be captured in full within five days.", "type": [ "boolean", "null" ] }, "company_id": { "description": "The ID of the company to create the payment for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "confirmation_token": { "description": "A confirmation token ID (ctok_) describing a payment method the buyer just supplied. Provide this INSTEAD of member_id and payment_method_id to charge a method that is not yet on file — the buyer is resolved from the token's billing email, or from `email`. The buyer may still have a step to complete (3DS, a redirect, linking a bank); poll the payment's status endpoint for what to do next.", "type": "string" }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the Whop user the payment belongs to. Ignored when the confirmation token was created by a signed-in buyer, and unless confirmation_token is provided.", "example": "buyer@example.com", "type": [ "string", "null" ] }, "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. Required unless confirmation_token is provided.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "plan_id": { "description": "An ID of an existing plan to use for the payment.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "promo_code_id": { "description": "The ID of an active promo code to apply to this payment. The promo code must belong to the company and be valid for the plan being purchased. The plan must be attached to a product — promo codes are not eligible for one-off purchases.", "example": "promo_xxxxxxxxxxxx", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters. Editable until they return — see the payment's update endpoint. Ignored unless confirmation_token is provided.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [ "company_id", "plan_id", "confirmation_token" ], "title": "CreatePaymentInputWithPlanIdAndConfirmationToken", "type": "object" }, { "description": "Autogenerated input type of CreatePayment", "properties": { "capture": { "description": "Whether to capture the card payment immediately. Pass false to place an authorization hold that must be captured in full within five days.", "type": [ "boolean", "null" ] }, "company_id": { "description": "The ID of the company to create the payment for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the Whop user the payment belongs to. Ignored when the confirmation token was created by a signed-in buyer, and unless confirmation_token is provided.", "example": "buyer@example.com", "type": [ "string", "null" ] }, "member_id": { "description": "The ID of the member to create the payment for. Required unless confirmation_token is provided.", "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. Required unless confirmation_token is provided.", "example": "pmt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "plan_id": { "description": "An ID of an existing plan to use for the payment.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "promo_code_id": { "description": "The ID of an active promo code to apply to this payment. The promo code must belong to the company and be valid for the plan being purchased. The plan must be attached to a product — promo codes are not eligible for one-off purchases.", "example": "promo_xxxxxxxxxxxx", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters. Editable until they return — see the payment's update endpoint. Ignored unless confirmation_token is provided.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [ "company_id", "plan_id", "member_id" ], "title": "CreatePaymentInputWithPlanIdAndMemberId", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Payment" }, { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "client_secret": { "description": "The credential the buyer's surface presents to poll this payment and set its return URL. Returned when a payment created from a confirmation token is created or retrieved by a caller with the payment:charge permission. Null for payments created from a stored payment method or callers without payment:charge. It unlocks this payment and nothing else; treat it like a password for that one attempt.", "example": "pay_xxxxxxxxxxxxxx_secret_v1_xxxx", "type": [ "string", "null" ] } }, "required": [ "client_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" }, "429": { "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": "Too many requests" }, "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", "shipment: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 - `shipment: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": { "allOf": [ { "$ref": "#/components/schemas/Payment" }, { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "client_secret": { "description": "The credential the buyer's surface presents to poll this payment and set its return URL. Returned when a payment created from a confirmation token is created or retrieved by a caller with the payment:charge permission. Null for payments created from a stored payment method or callers without payment:charge. It unlocks this payment and nothing else; treat it like a password for that one attempt.", "example": "pay_xxxxxxxxxxxxxx_secret_v1_xxxx", "type": [ "string", "null" ] } }, "required": [ "client_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" }, "429": { "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": "Too many requests" }, "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", "shipment:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Retrieve payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{id}/capture": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Captures the full amount of a card payment created with `capture: false`. The payment must still be in `requires_capture` before `capture_expires_at`. Partial capture, multiple captures, capturing more than the authorized amount, and tips are not supported.", "operationId": "capturePayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Payment captured" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Credential lacks a capture scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Payment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Capture payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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.", "example": "payment_processing_percentage_fee" } }, "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" }, "429": { "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": "Too many requests" }, "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 - `shipment: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" }, "429": { "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": "Too many requests" }, "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", "shipment: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 - `shipment: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" }, "429": { "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": "Too many requests" }, "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", "shipment: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 - `shipment: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" }, "429": { "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": "Too many requests" }, "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", "shipment:basic:read", "payment:dispute:read", "payment:resolution_center_case:read" ] } ], "summary": "Void payment", "tags": [ "Payments" ], "x-group-title": "Payins" } }, "/payments/{payment_id}/return_url": { "patch": { "description": "Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the payment's own `client_secret`, so the surface that knows the final destination can set it.", "operationId": "updateReturnUrlPayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters.", "example": "https://shinetime.example/checkout/thanks", "type": "string" } }, "required": [ "return_url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Return URL updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid return URL" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update payment return URL", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{payment_id}/status": { "get": { "description": "Retrieves how far a payment has got and what the buyer must do next, if anything. A payment is collected in the background, so poll this rather than reading the create response. Accepts either a secret key or the payment's own `client_secret`, so the surface collecting the payment can poll it directly.", "operationId": "retrieveStatusPayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Payment status retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Payment not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve payment status", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" } }, "/payouts": { "get": { "description": "Lists an account's or user's payouts, newest first.", "operationId": "listPayouts", "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 currency code filter, for example `usd`.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Filter to payouts whose `status` reads this word, matching exactly what this version displays — `reversed` finds settled payouts the bank later returned. Requires Api-Version-Date 2026-08-21 or later.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "type": "string" } }, { "description": "Filter by how the payout was created. Payouts created before source tracking or through internal tooling carry no source and never match.", "in": "query", "name": "source", "required": false, "schema": { "enum": [ "api", "dashboard", "automatic" ], "type": "string" } }, { "description": "Filter to payouts sent to one saved payout method (a pytk_ identifier). An unknown id matches nothing.", "in": "query", "name": "payout_method_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payouts created before this ISO 8601 time (exclusive).", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payouts created at or after this ISO 8601 time (inclusive).", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Number of payouts to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of payouts to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payouts listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdrawal:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account or user not found" } }, "security": [ { "bearerAuth": [ "payout:withdrawal:read" ] } ], "summary": "List Payouts", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Sends money from an account or user balance to a saved payout method for that owner.", "operationId": "createPayout", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 50.0, "currency": "usd", "notes": "Detailing supplies restock", "payout_method_id": "potk_xxxxxxxxxxxxxx", "speed": "standard" }, "required": [ "account_id" ] }, { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 50.0, "currency": "usd", "notes": "Detailing supplies restock", "payout_method_id": "potk_xxxxxxxxxxxxxx", "speed": "standard" }, "required": [ "user_id" ] } ], "properties": { "account_id": { "description": "Account to pay out from, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "acknowledge_bank_warning": { "description": "Set to `true` to continue when the destination bank could not confirm the payout method account holder's name, or `false` to have the payout refused in that case so the account holder can correct the name or link their bank first. Omitting the field skips the warning gate — a client that cannot show the warning keeps its pre-gate behavior.", "example": true, "type": "boolean" }, "amount": { "description": "The amount to pay out in the specified currency.", "example": 50.0, "format": "float", "type": "number" }, "currency": { "description": "The currency to pay out. Balances are held per currency and the payout draws only from the balance in this currency, so match the currency the funds arrived in — for example `cad` for an account funded by CAD transfers. Defaults to `usd`.", "example": "usd", "type": "string" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Key-value data to attach to the payout, echoed on every read and in webhook payloads. At most 50 keys, key names up to 40 characters, string values up to 500 characters. Never store secrets or regulated personal data here — webhook bodies are retained for delivery inspection.", "example": { "batch_id": "2026-08-18" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, "notes": { "description": "Free-form notes to attach to the payout, with a maximum of 255 characters. Omit or pass `null` for no notes.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "payout_method_id": { "description": "The saved payout method to deliver to (a potk_ identifier).", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "platform_covers_fees": { "description": "Whether the parent platform covers the payout fee instead of the account being paid out. Omit to use the platform's configured fee coverage policy; pass `false` to opt out of it. `true` is only accepted for accounts that belong to a platform, and requires the platform's policy to cover this payout method's category or a caller authorized to manage the platform's child account fees.", "example": true, "type": "boolean" }, "quote_token": { "description": "The server-signed quote_token returned by POST /payouts/quotes. When provided, Whop will not commit a provider payout below the destination amount the quote showed.", "example": "signed-payout-quote", "type": "string" }, "speed": { "default": "standard", "description": "How fast the funds should arrive. `instant` is only accepted when the account and payout method are eligible; otherwise the payout is rejected.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "user_id": { "description": "User to pay out from, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "payout_method_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "50.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Null until the payout settles; appears on the payout in GET /payouts once assigned.", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account. Null until the payout settles.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Null until the payout settles; appears on the payout in GET /payouts once assigned.", "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "2.5", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` — the id POST returns is the id GET /payouts lists. Conversion requests created before this version keep answering under their `cofr_` id.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout. Null until the payout settles.", "example": "MassPay", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Ops checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-payout-icon", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "Next Day Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "For a stablecoin payout, the id of the conversion request that funds it, prefixed `cofr_`; `null` on fiat payouts.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status, in the same vocabulary as GET /payouts.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "requested", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "pending_debit", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Always `null` here — it is assigned when the payout is submitted to the bank, and appears on the payout in GET /payouts once it has been sent; payouts not sent over ACH never get one.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" } } }, "description": "payout created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request is invalid or cannot be fulfilled, for example insufficient balance" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdraw_funds scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout method not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Create Payout", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/payouts/methods": { "get": { "description": "Lists the bank accounts, wallets, and crypto addresses an account or user can pay out to, newest first.", "operationId": "listPayoutMethods", "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 status filter. `created` means saved but unused, `active` means a payout through it succeeded, `broken` means the last payout failed and the method needs fixing.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "created", "active", "broken" ], "type": "string" } }, { "description": "Optional payout amount in whole currency units, for example `250.00`. When provided, each method includes a quote with the estimated fee, amount received, and delivery date for that amount.", "in": "query", "name": "amount", "required": false, "schema": { "type": "number" } }, { "description": "Currency code of the amount, for example `usd`. Only meaningful with amount or include_limits.", "in": "query", "name": "currency", "required": false, "schema": { "default": "usd", "type": "string" } }, { "description": "When true, the response also carries limits — the live per-speed payout caps the account's payout requests are validated against, in the requested currency. Requires the payout:withdrawal:read scope.", "in": "query", "name": "include_limits", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Number of payout methods to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of payout methods to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_reference": { "description": "Masked identifier for the destination, such as the last four digits of a bank account.", "example": "••••6789", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "verified", "type": [ "string", "null" ] }, "created_at": { "description": "When the payout method was added.", "example": "2026-06-15T09:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "description": "Currency payouts are delivered in for this method.", "example": "usd", "type": "string" }, "estimated_arrival": { "description": "Estimated arrival times before an amount-specific quote is requested. Null when the method is not currently eligible.", "properties": { "instant": { "description": "Estimated instant-delivery arrival, or null when unavailable.", "example": "2026-07-30T12:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "standard": { "description": "Estimated standard-delivery arrival, or null when unavailable.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "standard", "instant" ], "type": [ "object", "null" ] }, "fee_structure": { "description": "Configured fee terms for this payout method. Null when the method is not currently eligible. An amount-specific quote remains authoritative.", "properties": { "currency": { "description": "Currency code of fixed_amount.", "example": "usd", "type": "string" }, "fixed_amount": { "description": "Fixed fee charged, denominated in `currency`.", "example": 0.25, "format": "float", "type": "number" }, "percentage": { "description": "Percentage of the payout amount charged as a fee.", "example": 0.0, "format": "float", "type": "number" } }, "required": [ "percentage", "fixed_amount", "currency" ], "type": [ "object", "null" ] }, "id": { "description": "Payout method ID.", "example": "pyot_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "Name of the bank or institution receiving payouts.", "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "description": "Whether this is the default payout method for the account.", "example": true, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "example": "2026-08-02T15:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Business checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "description": "Display name of the payout rail, such as `ACH Bank Deposit`.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Fee and delivery estimate for paying out the requested amount through this method. Null unless an amount was provided, or when the estimate is unavailable.", "properties": { "amount": { "description": "The payout amount the quote is for.", "example": 500.0, "format": "float", "type": "number" }, "currency": { "description": "Currency of the quoted amount.", "example": "usd", "type": "string" }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency.", "example": 1.0, "format": "float", "type": "number" }, "instant": { "description": "Instant-delivery estimate. Null if the method does not support instant delivery, instant delivery is unavailable for the account, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 5.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 494.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] }, "max_limit": { "description": "Maximum payout amount for this method, in the payout currency.", "example": 25000.0, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount for this method, in the payout currency.", "example": 1.0, "format": "float", "type": "number" }, "standard": { "description": "Standard-delivery estimate. Null if the method does not support standard delivery, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 0.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 499.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] } }, "required": [ "amount", "currency", "exchange_rate", "min_limit", "max_limit", "standard", "instant" ], "type": [ "object", "null" ] }, "status": { "description": "Lifecycle status: `created` means saved but unused, `active` means a payout succeeded through it, `broken` means a payout failure disabled it; a later successful payout returns it to `active`.", "enum": [ "created", "active", "broken" ], "example": "active", "type": "string" }, "status_reason": { "description": "Machine-readable code for why the method is `broken` — the newest disabling failure recorded through it, whether a payout error or a pre-payout rejection. `null` unless the method is broken, or when it was disabled without a recorded failure.", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "The supported payout method this saved method was created from.", "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "country_code", "supports_standard_delivery", "supports_instant_delivery", "supports_plaid" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "bank_verification_state", "linked_via_plaid", "needs_plaid_reconnect", "is_clone", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" }, "type": "array" }, "limits": { "description": "The live per-speed payout caps for the account in the requested currency — the numbers a payout request is validated against at submit time, so clients can cap an amount input at a value the request will accept. Only present when include_limits is true.", "properties": { "currency": { "description": "The currency the caps are denominated in.", "example": "usd", "type": "string" }, "instant": { "description": "Caps for instant-speed payouts, which additionally draw on pending funds.", "properties": { "daily_amount_remaining": { "description": "How much of the account's daily instant allowance is left, in the requested currency. Null when the account is exempt from the daily cap, which is not the same as 0.", "example": 9999.0, "format": "float", "type": [ "number", "null" ] }, "error_code": { "description": "Why instant payouts are unavailable for this account, or null when they are available.", "enum": [ "amount_too_high", "account_daily_limit_reached", "restricted_account", "feature_disabled", null ], "example": "restricted_account", "type": [ "string", "null" ] }, "error_message": { "description": "Human-readable form of error_code, or null when instant payouts are available.", "example": "Instant payouts are not available for your account at this time.", "type": [ "string", "null" ] }, "max_amount": { "description": "The maximum amount an instant payout can move right now, in whole currency units. Already bounded by the remaining daily instant allowance; 0 while an eligibility error blocks instant payouts.", "example": 0.0, "format": "float", "type": "number" }, "resets_at": { "description": "When the daily instant allowance resets, or null when the account is exempt from the daily cap.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "max_amount", "error_code", "error_message", "daily_amount_remaining", "resets_at" ], "type": "object" }, "object": { "enum": [ "payout_limit" ], "example": "payout_limit", "type": "string" }, "standard": { "description": "Caps for standard-speed payouts, which draw on settled funds only.", "properties": { "max_amount": { "description": "The maximum amount a standard payout can move right now, in whole currency units.", "example": 500.0, "format": "float", "type": "number" } }, "required": [ "max_amount" ], "type": "object" } }, "required": [ "object", "currency", "standard", "instant" ], "type": "object" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payout methods listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:destination:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account or user not found" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "List Saved Payout Methods", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Saves a new place an account or user can pay out to. Sensitive details are vaulted in transit and never stored raw.", "operationId": "createPayoutMethod", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to add the payout method for, prefixed `biz_`. Provide this or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "destination_currency": { "default": "usd", "description": "Currency the supported payout method delivers payouts in.", "example": "usd", "type": "string" }, "fields": { "additionalProperties": { "type": "string" }, "description": "The supported payout method's required field values, keyed by field id — list them with `GET /payouts/supported_methods?supported_payout_method_id=...`. Field ids are stable `fld_` identifiers you may hardcode; they never change for a given field. A Basis Theory token id may be passed in place of a raw value. For a U.S. bank routing-number field, a raw nine-digit value must also pass the ABA checksum. A validation failure returns the method's full required_fields schema alongside the error. Required whenever the account details are supplied directly.", "example": { "fld_bank_account_number": "8825310472", "fld_bank_account_type": "Checking" }, "type": "object" }, "is_default": { "default": false, "description": "Whether to make this the account's default payout method.", "example": true, "type": "boolean" }, "nickname": { "description": "A label for the payout method, unique per destination.", "example": "Personal checking", "type": "string" }, "supported_payout_method_id": { "description": "The supported payout method to save (a podst_ identifier from a previous listing).", "example": "podst_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "The user to add the payout method for, prefixed `user_`. Provide this or `account_id`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "supported_payout_method_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_reference": { "description": "Masked identifier for the destination.", "example": "••••0472", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "no_data", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "example": "usd", "type": "string" }, "estimated_arrival": { "description": "Null on create. List payout methods to retrieve arrival estimates.", "type": [ "object", "null" ] }, "fee_structure": { "description": "Null on create. List payout methods to retrieve the configured fee terms.", "type": [ "object", "null" ] }, "id": { "description": "Payout method ID, usable as payout_method_id on POST /payouts.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "institution_name": { "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "example": false, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Ops checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Always null on create.", "type": [ "object", "null" ] }, "status": { "description": "Always `created` on create — no payout has used the method yet.", "enum": [ "created", "active", "broken" ], "example": "created", "type": "string" }, "status_reason": { "description": "Always `null` on create.", "type": [ "string", "null" ] }, "supported_payout_method": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit-icon", "type": [ "string", "null" ] }, "name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "supports_standard_delivery", "supports_instant_delivery" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": "destination_retired", "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" } } }, "description": "payout method created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request is invalid or the account has no payout setup yet" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:create_destination scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "supported payout method not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "payout setup is still being provisioned" } }, "security": [ { "bearerAuth": [ "payout:create_destination" ] } ], "summary": "Create Saved Payout Method", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/payouts/methods/{id}": { "delete": { "description": "Deletes a saved payout method so it can no longer receive payouts.", "operationId": "deletePayoutMethod", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted payout method, prefixed `potk_`.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "payout method deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:delete_destination scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout method not found" } }, "security": [ { "bearerAuth": [ "payout:delete_destination" ] } ], "summary": "Delete Saved Payout Method", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Payout method ID, prefixed `potk_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Changes the label used to identify a saved payout method or makes it the account's default payout method.", "operationId": "updatePayoutMethod", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "minProperties": 1, "properties": { "is_default": { "description": "Set to `true` to make this the account's default payout method. `false` is not accepted.", "enum": [ true ], "example": true, "type": "boolean" }, "nickname": { "description": "New label for the payout method, with at least one non-whitespace character and a maximum of 100 characters.", "example": "Primary checking", "maxLength": 100, "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_reference": { "description": "Masked identifier for the destination.", "example": "••••0472", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "no_data", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "example": "usd", "type": "string" }, "estimated_arrival": { "description": "`null` after an update. List payout methods to retrieve arrival estimates.", "type": [ "object", "null" ] }, "fee_structure": { "description": "`null` after an update. List payout methods to retrieve the configured fee terms.", "type": [ "object", "null" ] }, "id": { "description": "Payout method ID, prefixed `potk_`.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "institution_name": { "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "example": true, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Primary checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Always `null` after an update.", "type": [ "object", "null" ] }, "status": { "description": "`created` — saved, no payout has completed through it yet. `active` — a payout through it completed. `broken` — a payout through it failed with an error attributable to the method, and it no longer accepts payouts; a later successful payout returns it to `active`.", "enum": [ "created", "active", "broken" ], "example": "created", "type": "string" }, "status_reason": { "description": "Machine-readable code for why the method is `broken` — the newest failure recorded through it, whether a payout error or a pre-payout rejection. `null` unless the method is broken, or when it was disabled without a recorded failure.", "type": [ "string", "null" ] }, "supported_payout_method": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit-icon", "type": [ "string", "null" ] }, "name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "country_code", "supports_standard_delivery", "supports_instant_delivery", "supports_plaid" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": "destination_retired", "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "bank_verification_state", "linked_via_plaid", "needs_plaid_reconnect", "is_clone", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" } } }, "description": "payout method updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no update attributes are provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:update_destination scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout method not found" } }, "security": [ { "bearerAuth": [ "payout:update_destination" ] } ], "summary": "Update Saved Payout Method", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/payouts/quotes": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a short-lived, provider-backed quote for a payout. No funds move until the returned quote_token is submitted to POST /payouts. An Idempotency-Key header is required.", "operationId": "createPayoutQuote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to pay out from, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The amount to pay out in the specified currency.", "example": 6762.41, "format": "float", "type": "number" }, "currency": { "default": "usd", "description": "The balance currency to pay out.", "example": "eur", "type": "string" }, "payout_method_id": { "description": "The saved payout method to quote (a potk_ identifier).", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "platform_covers_fees": { "description": "Whether the parent platform covers the payout fee instead of the account being paid out.", "type": "boolean" }, "speed": { "default": "standard", "description": "How fast the funds should arrive.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "user_id": { "description": "User to pay out from, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "type": "string" } }, "required": [ "amount", "payout_method_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Gross payout amount." }, "destination_amount": { "$ref": "#/components/schemas/Money", "description": "Exact amount quoted for delivery." }, "exchange_rate": { "description": "Quoted exchange rate from the source currency to the destination currency.", "example": 4.13978443, "format": "float", "type": "number" }, "expires_at": { "description": "When the quote expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "fee": { "$ref": "#/components/schemas/Money", "description": "Fee charged for the payout." }, "id": { "description": "Provider-backed payout quote ID, prefixed `pout_`.", "example": "pout_aed_quote", "type": "string" }, "net_amount": { "$ref": "#/components/schemas/Money", "description": "Amount remaining after fees." }, "object": { "enum": [ "payout_quote" ], "example": "payout_quote", "type": "string" }, "quote_token": { "description": "Server-signed quote token to submit to POST /payouts.", "example": "signed-payout-quote", "type": "string" } }, "required": [ "object", "id", "amount", "fee", "net_amount", "destination_amount", "exchange_rate", "expires_at", "quote_token" ], "type": "object" } } }, "description": "payout quote created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "idempotency key is required" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the withdraw-funds scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Create Payout Quote", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/payouts/supported_methods": { "get": { "description": "Lists the payout methods an account or user is eligible to add.", "operationId": "listSupportedPayoutMethods", "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": "ISO 3166-1 alpha-2 country code for the bank account or wallet, such as `US`. Defaults to the country of supported_payout_method_id when one is given, otherwise the payout account's country.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Optional payout amount in whole currency units, for example `250.00`. When provided, each destination includes per-currency fee and delivery quotes.", "in": "query", "name": "amount", "required": false, "schema": { "type": "number" } }, { "description": "Currency code of the amount, for example `usd`. Only meaningful with amount.", "in": "query", "name": "currency", "required": false, "schema": { "default": "usd", "type": "string" } }, { "description": "Narrows the list to one supported payout method (a podst_ identifier) and includes the required_fields needed to save it as a payout method.", "in": "query", "name": "supported_payout_method_id", "required": false, "schema": { "type": "string" } }, { "description": "Currency the supported payout method would deliver payouts in. Only meaningful with supported_payout_method_id; required fields vary by destination currency.", "in": "query", "name": "destination_currency", "required": false, "schema": { "default": "usd", "type": "string" } }, { "description": "Number of supported payout methods to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of supported payout methods to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "delivery_type": { "description": "How funds are delivered, for example `bank_deposit`.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit", "type": [ "string", "null" ] }, "id": { "description": "Supported payout method ID.", "example": "podst_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Supported payout method display name.", "example": "SEPA Bank Transfer", "type": [ "string", "null" ] }, "object": { "enum": [ "supported_payout_method" ], "example": "supported_payout_method", "type": "string" }, "quotes": { "description": "Fee and delivery estimates for the requested amount, one per destination currency. Null unless an amount was provided.", "items": { "properties": { "amount": { "description": "The payout amount the quote is for.", "example": 2500.0, "format": "float", "type": "number" }, "currency": { "description": "Currency of the quoted amount.", "example": "usd", "type": "string" }, "destination_currency": { "description": "Currency the funds are delivered in.", "example": "usd", "type": "string" }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency.", "example": 1.0, "format": "float", "type": "number" }, "instant": { "description": "Instant-delivery estimate. Null if unsupported, unavailable for the account, or the amount does not cover the fee.", "properties": { "estimated_arrival": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "fee": { "example": 12.5, "format": "float", "type": "number" }, "total_received": { "example": 2487.5, "format": "float", "type": "number" } }, "required": [ "fee", "total_received", "estimated_arrival" ], "type": [ "object", "null" ] }, "max_limit": { "description": "Maximum payout amount, in the payout currency.", "example": 50000.0, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount, in the payout currency.", "example": 10.0, "format": "float", "type": "number" }, "standard": { "description": "Standard-delivery estimate. Null if unsupported or the amount does not cover the fee.", "properties": { "estimated_arrival": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "fee": { "example": 2.5, "format": "float", "type": "number" }, "total_received": { "example": 2497.5, "format": "float", "type": "number" } }, "required": [ "fee", "total_received", "estimated_arrival" ], "type": [ "object", "null" ] } }, "required": [ "destination_currency", "amount", "currency", "exchange_rate", "min_limit", "max_limit", "standard", "instant" ], "type": "object" }, "type": [ "array", "null" ] }, "required_fields": { "description": "Fields to collect before saving this supported payout method. Present only when supported_payout_method_id narrows the request to one method.", "items": { "properties": { "id": { "description": "Stable field ID (`fld_` + the semantic type), used as the field key when creating the payout method. Safe to hardcode — it never changes for a given field.", "example": "fld_bank_account_number", "type": "string" }, "input_type": { "description": "How to collect the value: `text`, `options`, or `date`.", "example": "text", "type": "string" }, "label": { "description": "Human-readable field name.", "example": "Account Number", "type": "string" }, "object": { "enum": [ "required_field" ], "example": "required_field", "type": "string" }, "options": { "description": "Allowed values for options fields.", "items": { "example": "savings", "type": "string" }, "type": [ "array", "null" ] }, "placeholder": { "description": "Example value.", "example": "8825310472", "type": [ "string", "null" ] }, "required": { "description": "Whether the field must be provided.", "example": true, "type": "boolean" }, "sensitive": { "description": "Whether the value is vaulted in transit and never stored raw.", "example": true, "type": "boolean" }, "type": { "description": "Semantic field type, for example `bank_account_number` or `swift`.", "example": "bank_account_number", "type": "string" }, "validation": { "description": "Regex the value must match. Null for options fields.", "example": "^[0-9]{4,17}$", "type": [ "string", "null" ] } }, "required": [ "object", "id", "label", "type", "input_type", "required", "validation", "options", "placeholder", "sensitive" ], "type": "object" }, "type": [ "array", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "object", "id", "name", "icon_url", "delivery_type", "supports_standard_delivery", "supports_instant_delivery", "quotes", "required_fields" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "MQ", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "supported payout methods listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:destination:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "supported payout method not found or not available for this account" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "List Supported Payout Methods", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/payouts/{id}": { "get": { "description": "Fetches one payout by its `wdrl_` ID, or by the `cofr_` conversion request ID a stablecoin payout carries as `payout_request_id` — both ids answer with the same payout object.", "operationId": "retrievePayout", "parameters": [ { "description": "Owning account ID, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Owning user ID, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts` or `cofr_` for a payout request returned by `POST /payouts`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. For a request retrieved by its own `cofr_` ID, this equals `id`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" } } }, "description": "payout found" }, "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 payout:withdrawal:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout not found" } }, "security": [ { "bearerAuth": [ "payout:withdrawal:read" ] } ], "summary": "Retrieve Payout", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts` or `cofr_` for the payout request returned by `POST /payouts`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payouts/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Payout ID, prefixed `wdrl_`, or the `cofr_` payout request ID returned by `POST /payouts` — both cancel the same payout.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a payout that is still in review and returns the funds, fees included, to the balance. A payout can be canceled while its status is `in_review`. A `requested` payout is still being prepared (its funds may be converting) and answers 409 until it reaches review; from `processing` on, the money is on its way and the answer is 409 with error type `not_cancelable`. Canceling a payout that is already canceled succeeds and returns it unchanged.", "operationId": "cancelPayout", "parameters": [ { "description": "Owning account ID, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Owning user ID, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "example": "Canceled by the account owner", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts` or `cofr_` for a payout request returned by `POST /payouts`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. For a request retrieved by its own `cofr_` ID, this equals `id`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "canceled", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" } } }, "description": "payout canceled and funds returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdraw_funds scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "payout is already processing" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Cancel Payout", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/people": { "get": { "description": "Lists the people (visitors and customers) of an account: the identity-linked person profiles aggregated from every pixel, payment, and platform event — identities, purchases and LTV, geo/device profile, traffic sources, and first/last marketing touches.", "operationId": "listPeople", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`. Optional for account API keys; required for credentials that can access multiple accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Search people by name, email, phone, or whop user ID (case-insensitive substring match).", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only include people acquired from any of these sources — canonical paths (whop:::, ext::..., referrer:, direct, other), exact or with a trailing :* prefix. The same vocabulary the events / people metrics use.", "explode": true, "in": "query", "name": "source", "required": false, "schema": { "items": { "example": "direct", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Attribution model the source filter matches against (defaults to last_touch).", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Only include people who fired any of these events, e.g. payment.completed or page.checkout.view.", "explode": true, "in": "query", "name": "event_name", "required": false, "schema": { "items": { "example": "payment.completed", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Only include people who fired this custom pixel event.", "in": "query", "name": "custom_event", "required": false, "schema": { "type": "string" } }, { "description": "With event_to plus an event or source filter, switches to exact-population mode: person ids are resolved and paginated on the events side within this window (the same query the people metric counts), then hydrated per page.", "in": "query", "name": "event_from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The inclusive end of the event window for exact-population mode.", "in": "query", "name": "event_to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people in this audience. An audience that keeps itself up to date resolves to the People filters that define it, so this always reflects who matches now; uploaded lists and point-in-time snapshots match their recorded members.", "in": "query", "name": "audience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only include the person linked to this whop user ID.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only include the person linked to this email address.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Only include the person linked to this phone number.", "in": "query", "name": "phone", "required": false, "schema": { "type": "string" } }, { "description": "Only include people whose most recent visit came from this ISO 3166-1 alpha-2 country code.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "true for customers only, false for people who have never purchased.", "in": "query", "name": "has_purchased", "required": false, "schema": { "type": "boolean" } }, { "description": "true for people who have an email address or phone number — the ones an ad platform can match.", "in": "query", "name": "contactable", "required": false, "schema": { "type": "boolean" } }, { "description": "Only include people first seen within this many days, as a rolling window.", "in": "query", "name": "first_seen_within_days", "required": false, "schema": { "type": "integer" } }, { "description": "Only include people last seen within this many days, as a rolling window.", "in": "query", "name": "last_seen_within_days", "required": false, "schema": { "type": "integer" } }, { "description": "Only include people first seen at or after this ISO 8601 timestamp.", "in": "query", "name": "first_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people first seen before this ISO 8601 timestamp.", "in": "query", "name": "first_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people last seen at or after this ISO 8601 timestamp.", "in": "query", "name": "last_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people last seen before this ISO 8601 timestamp.", "in": "query", "name": "last_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The number of people to return (default 100, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching people after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching people before a later page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Column to sort by. Defaults to last_seen_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "first_seen_at", "last_seen_at", "first_purchase_at", "last_purchase_at", "purchase_count", "event_count", "ltv", "aov", "name", "email" ], "type": "string" } }, { "description": "Sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "aov": { "example": 74.99, "type": "number" }, "device": { "properties": { "browser": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "device": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "os": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "email": { "description": "The email from the person's most recent event that carried one.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "event_count": { "example": 42, "type": "integer" }, "first_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "first_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "first_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "id": { "example": "prsn_123", "type": "string" }, "last_ip": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "last_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "last_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "last_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "location": { "properties": { "city": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "continent": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "country": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "ltv": { "example": 149.98, "type": "number" }, "member": { "description": "The user's member record at this account, when they are a member of it.", "properties": { "id": { "example": "mem_dana1", "type": "string" }, "joined_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "usd_total_spend": { "example": 149.98, "type": "number" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "name": { "description": "The name from the person's most recent event that carried one.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "phone": { "description": "The phone from the person's most recent event that carried one.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "purchase_count": { "example": 2, "type": "integer" }, "timezone": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "user": { "description": "The person's primary whop user, when one of their identities is a whop account.", "properties": { "id": { "example": "user_dana1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "profile_pic_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": "string" } }, "required": [ "id", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "account_id", "first_seen_at", "last_seen_at", "event_count", "purchase_count" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" }, "total_count": { "example": 42, "type": "integer" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "people listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid input" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "List People", "tags": [ "People" ] }, "x-whop-surface": "native" }, "/people/{id}": { "get": { "description": "Retrieves one person for an account. The identifier can be a person ID (prefixed `prsn_`), a user ID (prefixed `user_`), an email address, or a phone number — merged people resolve to the surviving profile.", "operationId": "retrievePerson", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The person ID, user ID, email address, or phone number to look up.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Optional for account API keys; required for credentials that can access multiple accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The full profile a retrieve returns: the summary plus every linked identity, purchase rows, all acquisition sources, and exact usage breakdowns.", "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "aov": { "example": 74.99, "type": "number" }, "audience_ids": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "custom_event_names": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "device": { "properties": { "browser": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "device": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "os": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "email": { "description": "The email from the person's most recent event that carried one.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "emails": { "description": "Every linked email, primary first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "event_count": { "example": 42, "type": "integer" }, "event_names": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "first_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "first_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "first_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "id": { "example": "prsn_123", "type": "string" }, "last_ip": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "last_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "last_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "last_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "location": { "properties": { "city": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "continent": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "country": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "ltv": { "example": 149.98, "type": "number" }, "member": { "description": "The user's member record at this account, when they are a member of it.", "properties": { "id": { "example": "mem_dana1", "type": "string" }, "joined_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "usd_total_spend": { "example": 149.98, "type": "number" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "name": { "description": "The name from the person's most recent event that carried one.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "names": { "description": "Every name the person's linked identities carried, primary first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "phone": { "description": "The phone from the person's most recent event that carried one.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "phones": { "description": "Every linked phone, primary first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "purchase_count": { "example": 2, "type": "integer" }, "purchases": { "items": { "properties": { "event_id": { "example": "evt_2", "type": "string" }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "usd_value": { "example": 74.99, "type": "number" } }, "required": [ "event_id", "usd_value", "occurred_at" ], "type": "object" }, "type": "array" }, "roles": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "sources": { "description": "Every distinct acquisition signal the person ever carried, ad entities hydrated.", "items": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": "object" }, "type": "array" }, "timezone": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "usage": { "description": "Exact usage breakdowns for the person's browser traffic (distinct events per value).", "properties": { "browser": { "items": { "properties": { "events": { "example": 10, "type": "integer" }, "value": { "example": "Chrome", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "city": { "items": { "properties": { "events": { "example": 9, "type": "integer" }, "value": { "example": "Austin", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "country": { "items": { "properties": { "events": { "example": 12, "type": "integer" }, "value": { "example": "US", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "device": { "items": { "properties": { "events": { "example": 5, "type": "integer" }, "value": { "example": "iPhone", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "ip": { "items": { "properties": { "events": { "example": 3, "type": "integer" }, "value": { "example": "1.1.1.1", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "os": { "items": { "properties": { "events": { "example": 7, "type": "integer" }, "value": { "example": "Mac OS X", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "referrer": { "items": { "properties": { "events": { "example": 4, "type": "integer" }, "value": { "example": "google.com", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "timezone": { "items": { "properties": { "events": { "example": 12, "type": "integer" }, "value": { "example": "America/Chicago", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" } }, "type": "object" }, "user": { "description": "The person's primary whop user, when one of their identities is a whop account.", "properties": { "id": { "example": "user_dana1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "profile_pic_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": "string" } }, "required": [ "id", "username" ], "type": [ "object", "null" ] }, "user_ids": { "description": "Every linked whop account, the most used one first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" } }, "required": [ "id", "account_id", "first_seen_at", "last_seen_at", "event_count", "purchase_count" ], "type": "object" } } }, "description": "person retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "person not found" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "Retrieve Person", "tags": [ "People" ] }, "x-whop-surface": "native" }, "/permissions": { "get": { "description": "Lists permission actions and whether the calling credential is granted each one for a resource. Answers for whichever identity authenticated the request — a user session, an OAuth token, or an account or app API key — so it never describes who else can reach the resource.", "operationId": "listPermissions", "parameters": [ { "description": "Tag of the resource to check against: an account (`biz_`), product (`prod_`), experience (`exp_`), or app (`app_`). A resource the credential cannot see is reported as granted nothing rather than as an error.", "in": "query", "name": "resource_id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated permission actions to check, for example `stats:read,payment:basic:read`. Every action is returned when omitted.", "in": "query", "name": "actions", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "action": { "$ref": "#/components/schemas/PermissionAction" }, "granted": { "description": "Whether the credential is granted the action for the resource.", "example": false, "type": "boolean" } }, "required": [ "action", "granted" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "permissions listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "Check Permissions", "tags": [ "Permissions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/plans": { "get": { "description": "Returns a paginated list of plans. Omit `account_id` and pass `product_ids` to list a product's public buyable plans.", "operationId": "listPlans", "parameters": [ { "description": "The unique identifier of the account to list plans for. Required unless `product_ids` is provided for a public product-plan read.", "in": "query", "name": "account_id", "required": false, "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", "expiration_days" ], "type": "string" } }, { "description": "Filter to only plans matching these release methods.", "in": "query", "name": "release_methods", "required": false, "schema": { "items": { "example": "buy_now", "type": "string" }, "type": "array" } }, { "description": "Filter to only plans matching these visibility states.", "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "example": "visible", "type": "string" }, "type": "array" } }, { "description": "Filter to only plans matching these billing types.", "in": "query", "name": "plan_types", "required": false, "schema": { "items": { "example": "renewal", "type": "string" }, "type": "array" } }, { "description": "Filter to only plans belonging to these product identifiers. When `account_id` is omitted, this is required and the response is publicly readable: only visible, non-invoice plans are returned.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxxx", "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": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "visible plans listed by product without authentication" }, "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": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "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.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "example": true, "type": [ "boolean", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this plan.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "example": "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" ], "example": "text", "type": "string" }, "id": { "description": "The ID of the custom field (if being updated).", "example": "field_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The name of the custom field.", "example": "Vehicle make and model", "type": "string" }, "order": { "description": "The order of the field.", "example": 1, "type": "integer" }, "placeholder": { "description": "An example response displayed in the input field.", "example": "2021 Audi S5", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "example": true, "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A text description of the plan displayed to customers on the product page.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days before the membership expires.", "example": 365, "type": [ "integer", "null" ] }, "image": { "description": "An image displayed on the product page to represent this plan.", "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial amount charged in the plan's currency, e.g. 10.43 for $10.43.", "example": 0, "type": [ "number", "null" ] }, "internal_notes": { "description": "Private notes visible only to the account owner. Not shown to customers.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` (a checkout call-to-action button label — one of the product custom CTA values, e.g. `subscribe`, `get_offer`) and `custom_cta_url` (a URL the button links to; web or `tel:`) override the product's call to action for this plan and are validated on save.", "example": { "bay": "2", "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club", "route": "north-austin" }, "type": [ "object", "null" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific plan.", "example": "inclusive", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the plan. When not provided, the account's defaults apply.", "properties": { "disabled": { "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan_type": { "description": "Plan billing type, such as `one_time` or `renewal`.", "example": "renewal", "type": "string" }, "product_id": { "description": "The unique identifier of the product to attach this plan to.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this plan.", "example": "buy_now", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring plans, in the plan's currency.", "example": 59, "type": [ "number", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses.", "example": 4, "type": [ "integer", "null" ] }, "stock": { "description": "The maximum number of units available for purchase. Ignored when unlimited_stock is true.", "example": 25, "type": [ "integer", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this plan. Send `null` to inherit the account default.", "enum": [ "mandate_challenge", "frictionless" ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "The display name of the plan shown to customers on the product page.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial duration before the first recurring charge.", "example": 7, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When true, the stock field is ignored.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "example": "visible", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "plan created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:create" ] } ], "summary": "Create Plan", "tags": [ "Plans" ] }, "x-whop-surface": "native" }, "/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": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted plan.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "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": [ "plan:basic:read" ] } ], "summary": "Retrieve Plan", "tags": [ "Plans" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Plan ID, prefixed `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.", "example": true, "type": [ "boolean", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "cancel_discount_intervals": { "description": "How many renewals the retention discount applies to. Required when `offer_cancel_discount` is true.", "example": 3, "type": [ "integer", "null" ] }, "cancel_discount_percentage": { "description": "Percentage taken off each discounted renewal. Required when `offer_cancel_discount` is true.", "example": 20, "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this plan.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the plan's pricing. Defaults to USD.", "example": "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" ], "example": "text", "type": "string" }, "id": { "description": "The ID of the custom field (if being updated).", "example": "field_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The name of the custom field.", "example": "Vehicle make and model", "type": "string" }, "order": { "description": "The order of the field.", "example": 1, "type": "integer" }, "placeholder": { "description": "An example response displayed in the input field.", "example": "2021 Audi S5", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "example": true, "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A text description of the plan displayed to customers on the product page.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days before the membership expires.", "example": 365, "type": [ "integer", "null" ] }, "image": { "description": "An image displayed on the product page to represent this plan.", "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial amount charged in the plan's currency, e.g. 10.43 for $10.43.", "example": 0, "type": [ "number", "null" ] }, "internal_notes": { "description": "Private notes visible only to the account owner. Not shown to customers.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` (a checkout call-to-action button label — one of the product custom CTA values, e.g. `subscribe`, `get_offer`) and `custom_cta_url` (a URL the button links to; web or `tel:`) override the product's call to action for this plan and are validated on save.", "example": { "bay": "2", "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club", "route": "north-austin" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether to offer a retention discount when a customer attempts to cancel.", "example": true, "type": [ "boolean", "null" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific plan.", "example": "inclusive", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the plan. When not provided, the account's defaults apply.", "properties": { "disabled": { "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "release_method": { "description": "Sales method for this plan.", "example": "buy_now", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring plans, in the plan's currency.", "example": 59, "type": [ "number", "null" ] }, "stock": { "description": "The maximum number of units available for purchase. Ignored when unlimited_stock is true.", "example": 25, "type": [ "integer", "null" ] }, "strike_through_initial_price": { "description": "A comparison price displayed with a strikethrough for the initial price.", "example": 99, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "A comparison price displayed with a strikethrough for the renewal price.", "example": 79, "type": [ "number", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this plan. Send `null` to inherit the account default.", "enum": [ "mandate_challenge", "frictionless" ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "The display name of the plan shown to customers on the product page.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial duration before the first recurring charge.", "example": 7, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When true, the stock field is ignored.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "example": "visible", "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" ] }, "x-whop-surface": "native" }, "/plans/{id}/calculate_tax": { "parameters": [ { "description": "Plan ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Previews tax for a plan before checkout, based on the buyer's location.", "operationId": "calculatePlanTax", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "address": { "country": "DE", "postal_code": "10115" } }, "properties": { "address": { "description": "Buyer billing address used for tax calculation. Provide either `address.country` or `ip_address`; include state and postal code when available for more accurate results.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "country" ], "type": [ "object", "null" ] }, "ip_address": { "description": "Buyer IP address used to infer location when no billing address is provided.", "example": "1.2.3.4", "type": "string" }, "tax_ids": { "description": "Optional buyer tax ID for B2B exemptions. At most one entry is supported.", "items": { "properties": { "type": { "description": "Tax ID type, such as `eu_vat` for an EU VAT number.", "enum": [ "ad_nrt", "ao_tin", "ar_cuit", "al_tin", "am_tin", "aw_tin", "au_abn", "au_arn", "eu_vat", "az_tin", "bs_tin", "bh_vat", "bd_bin", "bb_tin", "by_tin", "bj_ifu", "bo_tin", "ba_tin", "br_cnpj", "br_cpf", "bg_uic", "bf_ifu", "kh_tin", "cm_niu", "ca_bn", "ca_gst_hst", "ca_pst_bc", "ca_pst_mb", "ca_pst_sk", "ca_qst", "cv_nif", "cl_tin", "cn_tin", "co_nit", "cd_nif", "cr_tin", "hr_oib", "do_rcn", "ec_ruc", "eg_tin", "sv_nit", "et_tin", "eu_oss_vat", "ge_vat", "gh_tin", "de_stn", "gb_vat", "gn_nif", "hk_br", "hu_tin", "is_vat", "in_gst", "id_npwp", "il_vat", "jp_cn", "jp_rn", "jp_trn", "kz_bin", "ke_pin", "kg_tin", "la_tin", "li_uid", "li_vat", "my_frp", "my_itn", "my_sst", "mr_nif", "mx_rfc", "md_vat", "me_pib", "ma_vat", "np_pan", "nz_gst", "ng_tin", "mk_vat", "no_vat", "no_voec", "om_vat", "pe_ruc", "ph_tin", "ro_tin", "ru_inn", "ru_kpp", "sa_vat", "sn_ninea", "rs_pib", "sg_gst", "sg_uen", "si_tin", "za_vat", "kr_brn", "es_cif", "ch_uid", "ch_vat", "tw_vat", "tj_tin", "tz_vat", "th_vat", "tr_tin", "ug_tin", "ua_vat", "ae_trn", "us_ein", "uy_ruc", "uz_tin", "uz_vat", "ve_rif", "vn_tin", "zm_tin", "zw_tin", "sr_fin" ], "example": "us_ein", "type": "string" }, "value": { "description": "Tax ID value, for example `DE123456789`.", "example": "12-3456789", "type": "string" } }, "type": "object" }, "maxItems": 1, "type": [ "array", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "example": { "currency": "usd", "status": "calculated", "subtotal": 1000, "tax_amount": 70, "tax_behavior": "exclusive", "total": 1070 }, "properties": { "currency": { "description": "Three-letter ISO 4217 currency code for the returned amounts.", "example": "usd", "type": "string" }, "status": { "description": "Whether Whop calculated tax for this preview. `not_calculated` means no tax could be determined, so `tax_amount` is 0 and `total` equals `subtotal`.", "enum": [ "calculated", "not_calculated" ], "example": "calculated", "type": "string" }, "subtotal": { "description": "Plan price in the currency's smallest unit, for example cents. For exclusive tax, this is the pre-tax amount; for inclusive tax, it already includes tax and equals the total.", "example": 1000, "type": "integer" }, "tax_amount": { "description": "Calculated tax amount in the currency's smallest unit. For exclusive tax, this is added on top of the subtotal; for inclusive tax, it is the portion of the subtotal that is tax.", "example": 70, "type": "integer" }, "tax_behavior": { "description": "Whether tax is added on top of the plan price or already included in it for this buyer's location.", "enum": [ "exclusive", "inclusive" ], "example": "exclusive", "type": "string" }, "total": { "description": "Amount the buyer would pay in the currency's smallest unit.", "example": 1070, "type": "integer" } }, "required": [ "currency", "tax_behavior", "subtotal", "tax_amount", "total", "status" ], "type": "object" } } }, "description": "tax calculated" }, "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 plan read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "plan not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Calculate Tax", "tags": [ "Plans" ] }, "x-whop-surface": "native" }, "/products": { "get": { "description": "Returns a paginated list of products. Omit `account_id` to search the public marketplace.", "operationId": "listProducts", "parameters": [ { "description": "The unique identifier of the account to list products for. Omit to search the public marketplace.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Ranked search against product title and headline. Omit to browse by recency.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only return marketplace products assigned to this category route, such as `trading`.", "in": "query", "name": "marketplace_category_route", "required": false, "schema": { "type": "string" } }, { "description": "Filter to products with a buyable plan of these billing models, such as `one_time` or `renewal`.", "in": "query", "name": "plan_types", "required": false, "schema": { "items": { "enum": [ "renewal", "one_time" ], "type": "string" }, "type": "array" } }, { "description": "Only return products whose advertised buyable plan has a displayed price of at least this amount. Recurring plans use renewal price.", "in": "query", "name": "price_minimum", "required": false, "schema": { "type": "number" } }, { "description": "Only return products whose advertised buyable plan has a displayed price of at most this amount. Recurring plans use renewal price.", "in": "query", "name": "price_maximum", "required": false, "schema": { "type": "number" } }, { "description": "Filter to only products matching these visibility states. Ignored on the public marketplace list, which only returns visible products.", "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "example": "visible", "type": "string" }, "type": "array" } }, { "description": "Filter to only products matching these types.", "in": "query", "name": "access_pass_types", "required": false, "schema": { "items": { "example": "regular", "type": "string" }, "type": "array" } }, { "description": "Filter to only products carrying all of these labels. Labels are matched lowercased.", "in": "query", "name": "labels", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "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. Account lists default to `created_at`. Marketplace lists default to `discoverable_at` and accept `created_at` or `discoverable_at`. Cannot be combined with `query`.", "in": "query", "name": "order", "required": false, "schema": { "type": "string" } }, { "description": "The number of products to return (default and max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns products after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of products to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns products before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Only return products created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return products created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "marketplace products listed without an account" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "marketplace order cannot be combined with query" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ {}, { "bearerAuth": [ "access_pass:basic:read" ] } ], "summary": "List Products", "tags": [ "Products" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a new product for an account.", "operationId": "createProduct", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account to create this product for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "example": false, "type": [ "boolean", "null" ] }, "custom_cta": { "description": "The call-to-action button label.", "enum": [ "get_access", "join", "order_now", "shop_now", "call_now", "donate_now", "contact_us", "sign_up", "subscribe", "purchase", "get_offer", "apply_now", "complete_order", null ], "example": "order_now", "type": [ "string", "null" ] }, "custom_cta_url": { "description": "A URL the call-to-action button links to.", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "Custom bank statement descriptor. Must start with WHOP*.", "example": "WHOP*SHINETIME", "type": [ "string", "null" ] }, "description": { "description": "A written description displayed on the product page.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "type": [ "string", "null" ] }, "global_affiliate_percentage": { "description": "The commission rate affiliates earn.", "example": 10, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "The enrollment status in the global affiliate program.", "enum": [ "enabled", "disabled" ], "example": "enabled", "type": "string" }, "headline": { "description": "A short marketing headline for the product page.", "example": "Steam, shampoo, and odor removal in one visit", "type": [ "string", "null" ] }, "labels": { "description": "Labels used to group products into collections. Stored lowercased and de-duplicated. Maximum 20 labels, 50 characters each.", "items": { "example": "interior", "type": "string" }, "type": [ "array", "null" ] }, "member_affiliate_percentage": { "description": "The commission rate members earn.", "example": 5, "type": [ "number", "null" ] }, "member_affiliate_status": { "description": "The enrollment status in the member affiliate program.", "enum": [ "enabled", "disabled" ], "example": "enabled", "type": "string" }, "metadata": { "description": "Custom key-value pairs to store on the product.", "example": { "bay": "1", "duration_hours": "4" }, "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "The unique identifier of the tax classification code. See the available [product categories](https://docs.numeral.com/essentials/product-categories).", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "A URL to redirect the customer to after purchase.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "route": { "description": "The URL slug for the product's public link.", "example": "interior-deep-clean", "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.", "example": true, "type": [ "boolean", "null" ] }, "title": { "description": "The display name of the product. Maximum 80 characters.", "example": "Interior Deep Clean", "type": "string" }, "visibility": { "description": "Whether the product is visible to customers.", "example": "visible", "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product created" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:create" ] } ], "summary": "Create Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/products/{id}": { "delete": { "description": "Deletes a product. Only products with no memberships, entries, reviews, or invoices can be deleted.", "operationId": "deleteProduct", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted product.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "product deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" } }, "security": [ { "bearerAuth": [ "access_pass:delete" ] } ], "summary": "Delete Product", "tags": [ "Products" ] }, "get": { "description": "Retrieves a product. Public — no credentials.", "operationId": "retrieveProduct", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product retrieved without authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" } }, "security": [], "summary": "Retrieve Product", "tags": [ "Products" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the product.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an existing product.", "operationId": "updateProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "banner_image": { "description": "A wide image for the product, shown on the product page and on listing cards. Pass `{ id }` for an existing attachment or `{ direct_upload_id }` for a completed direct upload; `null` removes it.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "description": { "description": "A written description displayed on the product page.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "type": [ "string", "null" ] }, "headline": { "description": "A short marketing headline for the product page.", "example": "Steam, shampoo, and odor removal in one visit", "type": [ "string", "null" ] }, "labels": { "description": "Labels used to group products into collections. Replaces the existing labels. Send an empty array to clear them.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the product.", "example": { "bay": "1", "duration_hours": "4" }, "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "The unique identifier of the tax classification code. See the available [product categories](https://docs.numeral.com/essentials/product-categories).", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "send_welcome_message": { "description": "Whether to send an automated welcome message via support chat when a user joins this product.", "example": true, "type": [ "boolean", "null" ] }, "title": { "description": "The display name of the product.", "example": "Interior Deep Clean", "type": "string" }, "visibility": { "description": "Whether the product is visible to customers.", "example": "visible", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product tax code updated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" } }, "security": [ { "bearerAuth": [ "access_pass:update" ] } ], "summary": "Update Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/products/{id}/publish": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the product, prefixed `prod_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Submits a product to the whop.com marketplace for review. The product moves to `pending_review`; a Whop reviewer approves it before it goes live.", "operationId": "publishProduct", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product submitted for review" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:update" ] } ], "summary": "Publish Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/products/{id}/unpublish": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the product, prefixed `prod_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Removes a product from the whop.com marketplace. The product moves to `not_available`.", "operationId": "unpublishProduct", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product removed from the marketplace" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:update" ] } ], "summary": "Unpublish Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/promo_codes": { "get": { "description": "Lists promo codes for an account with cursor pagination, filters, and sorting.", "operationId": "listPromoCodes", "parameters": [ { "description": "Account whose promo codes are listed (`biz_` tag).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Promo-code status. `expired` groups inactive and archived codes.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "inactive", "archived", "expired" ], "type": "string" } }, { "description": "Only promo codes scoped to these product IDs.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only promo codes scoped to these plan IDs.", "in": "query", "name": "plan_ids", "required": false, "schema": { "items": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only promo codes created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only promo codes created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of promo codes to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of promo codes to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PromoCodeListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "promo codes listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "promo_code:basic:read" ] } ], "summary": "List Promo Codes", "tags": [ "Promo Codes" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a promo code for an account. First-party sessions may attach an affiliate.", "operationId": "createPromoCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount_off": { "example": 25, "type": "number" }, "base_currency": { "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" ], "example": "usd", "type": "string" }, "churned_users_only": { "example": false, "type": "boolean" }, "code": { "example": "AFFILIATE25", "type": "string" }, "existing_memberships_only": { "example": false, "type": "boolean" }, "expires_at": { "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "new_users_only": { "example": true, "type": "boolean" }, "one_per_customer": { "example": true, "type": "boolean" }, "plan_ids": { "items": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "product_id": { "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "promo_duration_months": { "example": 3, "type": "integer" }, "promo_type": { "enum": [ "percentage", "flat_amount" ], "example": "percentage", "type": "string" }, "stock": { "example": 200, "type": [ "integer", "null" ] }, "unlimited_stock": { "example": false, "type": "boolean" } }, "required": [ "account_id", "amount_off", "base_currency", "code", "new_users_only", "promo_duration_months", "promo_type" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code created" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "promo_code:create" ] } ], "summary": "Create Promo Code", "tags": [ "Promo Codes" ] }, "x-whop-surface": "native" }, "/promo_codes/{id}": { "delete": { "description": "Archives a promo code so it cannot be used in future checkouts.", "operationId": "deletePromoCode", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "promo_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "promo code deleted" } }, "security": [ { "bearerAuth": [ "promo_code:delete" ] } ], "summary": "Delete Promo Code", "tags": [ "Promo Codes" ] }, "get": { "description": "Retrieves a promo code by ID.", "operationId": "retrievePromoCode", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "promo code not found" } }, "security": [ { "bearerAuth": [ "promo_code:basic:read" ] } ], "summary": "Retrieve Promo Code", "tags": [ "Promo Codes" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/promo_codes/{id}/activate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Turns an inactive promo code back on so it can be redeemed at checkout.", "operationId": "activatePromoCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code activated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "promo code archived" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "promo_code:update" ] } ], "summary": "Activate Promo Code", "tags": [ "Promo Codes" ] }, "x-whop-surface": "native" }, "/promo_codes/{id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Turns off an active promo code so it can no longer be redeemed at checkout.", "operationId": "deactivatePromoCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code deactivated" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "promo_code:update" ] } ], "summary": "Deactivate Promo Code", "tags": [ "Promo Codes" ] }, "x-whop-surface": "native" }, "/reactions": { "get": { "description": "Returns a paginated list of emoji reactions on a specific message or forum post, sorted by most recent.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_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 (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_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 (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_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" }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Delete reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing reaction.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_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" }, "429": { "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": "Too many requests" }, "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" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" } }, "/recommended_actions": { "get": { "description": "Lists the recommended action chains for an account — short sequences of actions (create a product, price it, publish it) the account should run next, gated on what it already has.", "operationId": "listRecommendedActions", "parameters": [ { "description": "Account ID, prefixed `biz_`. Defaults to the API key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AccountRecommendedActionChain" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "defaults to the API key's own account" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not visible to the credential" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "List Action Chains", "tags": [ "Recommended Actions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/recommended_actions/{id}": { "get": { "description": "Retrieves a recommended action chain by id, including chains that have already been run. Seeded chains are reconstructed from their hard-coded chain; generated chains are read from the account's stored chain, with each step's filled-in input.", "operationId": "retrieveRecommendedAction", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRecommendedActionChain" } } }, "description": "generated chain retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown chain" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Retrieve Action Chain", "tags": [ "Recommended Actions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Chain ID from the list endpoint, e.g. `rac_seed_start_selling_9f2c1a7b04`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Defaults to the API key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "post": { "description": "Records that the caller ran a recommended action chain. Nothing is executed server-side yet — the client follows the chain's step CTAs itself; this writes the `recommended_action_chain.executed` analytics event.", "operationId": "runRecommendedAction", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "chain_id": { "example": "rac_chain_xxxxxxxxxxxx", "type": "string" }, "execution": { "enum": [ "redirect", "executed" ], "example": "redirect", "type": "string" } }, "required": [ "chain_id", "execution" ], "type": "object" } } }, "description": "run recorded" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown chain" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Execute Action Chain", "tags": [ "Recommended Actions" ] }, "x-whop-surface": "native" }, "/recommended_actions/{id}/executions": { "get": { "description": "Lists the per-step record of a recommended action chain the server ran — one entry per step in position order, each carrying its current status and, once the step completed, the API response it produced. A chain that was never run server-side returns an empty list.", "operationId": "listRecommendedActionExecutions", "parameters": [ { "description": "Chain ID from the list endpoint.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Defaults to the API key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "chain_id": { "description": "The chain these executions belong to.", "example": "rac_chain_xxxxxxxxxxxx", "type": "string" }, "executions": { "description": "One entry per run step, in position order.", "items": { "$ref": "#/components/schemas/RecommendedActionExecution" }, "type": "array" } }, "required": [ "chain_id", "executions" ], "type": "object" } } }, "description": "executions listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown chain" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "List Recommended Action Executions", "tags": [ "Recommended Actions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "payment_id", "required": false, "schema": { "description": "Filter refunds to those associated with this specific payment. Mutually exclusive with company_id and user_id: provide exactly one.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Filter refunds to those belonging to this company. Mutually exclusive with payment_id and user_id: provide exactly one.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter refunds to those associated with this specific user. Mutually exclusive with payment_id and company_id: provide exactly one. Requires a credential belonging to that user; any other credential receives 'You are not authorized'.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for ordering results, either ascending or descending." }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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": "Lists resolution center cases. Without `account_id` you get every case you can read — the ones you opened as a buyer and every account you are a team member of; the filters narrow that list.", "operationId": "listResolutionCenterCases", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Only cases filed against this account (`biz_` tag). With read access to the account this lists its whole queue; without, only the cases you opened against it.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only cases opened by this customer — a `user_` tag, or `me` for the calling user. It narrows what you can already read, so `me` lists the cases you opened without the ones on accounts you are a team member of.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "The number of cases to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns cases after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of cases to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns cases before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort cases by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "response_due_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only cases in these statuses. Repeat the parameter to pass several — one paginated list covers all of them.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "example": "awaiting_merchant", "type": "string" }, "type": "array" } }, { "description": "Only cases opened for these reasons. Repeat the parameter to pass several.", "in": "query", "name": "reason", "required": false, "schema": { "items": { "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "fraudulent", "type": "string" }, "type": "array" } }, { "description": "Only closed cases that ended these ways. Repeat the parameter to pass several.", "in": "query", "name": "outcome", "required": false, "schema": { "items": { "enum": [ "customer_won", "merchant_won", "withdrawn" ], "example": "customer_won", "type": "string" }, "type": "array" } }, { "description": "Only cases created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only cases created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "cases listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account_id" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "List Resolution Center Cases", "tags": [ "Resolution Center Cases" ] }, "post": { "description": "Opens a case, as the customer, against one of your own payments. Provide the payment (`receipt_id`), the `reason`, and a `message`.", "operationId": "createResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "The customer's explanation.", "example": "The mobile detailer never showed up for the Ceramic Coating appointment.", "type": "string" }, "reason": { "description": "What went wrong. Uses the same vocabulary as `/disputes`.", "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "product_not_received", "type": "string" }, "receipt_id": { "description": "The payment to open the case against (`pay_` tag).", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "receipt_id", "reason", "message" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case opened" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Open a Case as the Customer", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/summary": { "get": { "description": "Aggregates the same cases `GET /resolution_center_cases` lists, using the same filters. Use it to build status tabs and issue filters without paging the whole list.", "operationId": "retrieveResolutionCenterCaseSummary", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Which breakdowns to return, keyed by these names under `groups`. Repeat the parameter to ask for several; omit it for all of them.", "in": "query", "name": "groups", "required": false, "schema": { "items": { "enum": [ "status", "reason", "outcome" ], "example": "status", "type": "string" }, "type": "array" } }, { "description": "The account to summarize cases for (`biz_` tag).", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only cases opened by this customer — a `user_` tag, or `me` for the calling user.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only cases in these statuses.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "example": "awaiting_merchant", "type": "string" }, "type": "array" } }, { "description": "Only cases opened for these reasons.", "in": "query", "name": "reason", "required": false, "schema": { "items": { "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "fraudulent", "type": "string" }, "type": "array" } }, { "description": "Only closed cases that ended these ways.", "in": "query", "name": "outcome", "required": false, "schema": { "items": { "enum": [ "customer_won", "merchant_won", "withdrawn" ], "example": "customer_won", "type": "string" }, "type": "array" } }, { "description": "Only count cases created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only count cases created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groups": { "description": "One entry per requested breakdown, keyed by the field it groups on. A field you did not ask for is absent.", "properties": { "outcome": { "description": "How many of the matching cases ended each way. Every outcome is present, including those with a count of zero; open cases are counted in none of them.", "properties": { "customer_won": { "example": 0, "type": "integer" }, "merchant_won": { "example": 0, "type": "integer" }, "withdrawn": { "example": 0, "type": "integer" } }, "required": [ "customer_won", "merchant_won", "withdrawn" ], "type": "object" }, "reason": { "description": "How many of the matching cases were opened for each reason. Every reason is present, including those with a count of zero.", "properties": { "fraudulent": { "example": 0, "type": "integer" }, "not_as_described": { "example": 0, "type": "integer" }, "product_not_received": { "example": 1, "type": "integer" }, "product_unacceptable": { "example": 0, "type": "integer" }, "subscription_canceled": { "example": 0, "type": "integer" } }, "required": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "type": "object" }, "status": { "description": "How many of the matching cases are in each status. Every status is present, including those with a count of zero.", "properties": { "awaiting_customer": { "example": 0, "type": "integer" }, "awaiting_merchant": { "example": 1, "type": "integer" }, "closed": { "example": 0, "type": "integer" }, "under_review": { "example": 0, "type": "integer" } }, "required": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "type": "object" } }, "type": "object" }, "total": { "description": "How many cases match the filters.", "example": 1, "type": "integer" } }, "required": [ "total", "groups" ], "type": "object" } } }, "description": "summary returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized breakdown" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "Retrieve Resolution Center Case Summary", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}": { "get": { "description": "Retrieves a single resolution center case with its full event timeline.", "operationId": "retrieveResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no case with that ID" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "Retrieve Resolution Center Case", "tags": [ "Resolution Center Cases" ] }, "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/resolution_center_cases/{id}/accept": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Accepts the case in the customer's favor, as the merchant: refunds the payment in full and closes the case.", "operationId": "acceptResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "An optional note to the customer, recorded on the case timeline.", "example": "Refunding the deposit in full — we could not make the Austin booking window.", "type": "string" }, "terminate_membership": { "description": "Whether to also terminate the customer's membership.", "example": false, "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case accepted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required write scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] } ], "summary": "Accept a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/appeal": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Appeals a decision, as the customer, on a case that closed in the merchant's favor. Escalates the case to Whop for platform review. A case can be appealed once.", "operationId": "appealResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "Why you are appealing the decision.", "example": "The coating is already flaking on the hood two weeks later.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case appealed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Appeal a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/deny": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Denies the case, as the merchant: rejects the claim and closes the case with no refund.", "operationId": "denyResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "Why the claim is being denied. Shown to the customer.", "example": "The ceramic coating was applied and the vehicle was collected on 2026-01-05.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case denied" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] } ], "summary": "Deny a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/events": { "get": { "description": "Lists the case timeline, newest first. Events the viewer is not allowed to see are omitted — a customer reads the customer-visible timeline, the merchant reads the full one.", "operationId": "listResolutionCenterCaseEvents", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The number of events to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns events after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of events to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns events before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ResolutionEvent" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "events listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no case with that ID" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "List Resolution Center Case Events", "tags": [ "Resolution Center Cases" ] }, "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/resolution_center_cases/{id}/reply": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Replies to an open request for information on the case. As the merchant this answers Whop's request (valid while the case awaits your information); as the customer it provides the information requested from you. The actor is resolved from the credential.", "operationId": "replyToResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "The reply to add to the case.", "example": "Here are the before and after photos from the Burnet Rd bay.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "reply added" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] }, { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Reply to a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/request_info": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Asks the customer for more information, as the merchant. Allowed up to 3 times per case before you must accept or deny it.", "operationId": "requestResolutionCenterCaseInfo", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "What you need from the customer.", "example": "Please send a photo of the panels you are unhappy with.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "information requested" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] } ], "summary": "Request Information from the Customer", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/withdraw": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Withdraws (cancels) a case you opened, as the customer. Only possible while the case is still open.", "operationId": "withdrawResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case withdrawn" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Withdraw a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "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" }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for ordering results, either ascending or descending." }, "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" }, "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" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "post": { "description": "Save a buyer's payment method for later without charging it. Provide a confirmation token for a method the buyer just supplied, or an existing payment method to re-verify. The buyer may still have a step to complete — 3D Secure, a hosted enrollment, linking a bank account — so poll the setup intent's status endpoint for what to do next.\n\nRequired permissions:\n - `payment:charge`\n - `member:basic:read`\n - `member:email:read`", "operationId": "createSetupIntent", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateSetupIntent", "oneOf": [ { "description": "Autogenerated input type of CreateSetupIntent", "properties": { "company_id": { "description": "The ID of the company to save the payment method for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "confirmation_token": { "description": "A confirmation token ID (ctok_) describing a payment method the buyer just supplied. Provide this or payment_method_id, not both.", "example": "ctok_xxxxxxxxxxxxxx", "type": "string" }, "currency": { "description": "The currency the saved payment method will be used with. Controls which currency-specific payment methods are available. Defaults to usd.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the Whop user the method belongs to. Ignored when the caller IS the buyer or the confirmation token was created by a signed-in buyer, and unless confirmation_token is provided.", "example": "buyer@example.com", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom metadata to attach to the setup intent.", "type": [ "object", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [ "company_id", "confirmation_token" ], "title": "CreateSetupIntentInputWithConfirmationToken", "type": "object" }, { "description": "Autogenerated input type of CreateSetupIntent", "properties": { "company_id": { "description": "The ID of the company to save the payment method for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "currency": { "description": "The currency the saved payment method will be used with. Controls which currency-specific payment methods are available. Defaults to usd.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the Whop user the method belongs to. Ignored when the caller IS the buyer or the confirmation token was created by a signed-in buyer, and unless confirmation_token is provided.", "example": "buyer@example.com", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom metadata to attach to the setup intent.", "type": [ "object", "null" ] }, "payment_method_id": { "description": "An existing payment method (payt_) to re-verify and save. Provide this or confirmation_token, not both.", "example": "pmt_xxxxxxxxxxxxxx", "type": "string" }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters.", "example": "https://example.com/path", "type": [ "string", "null" ] } }, "required": [ "company_id", "payment_method_id" ], "title": "CreateSetupIntentInputWithPaymentMethodId", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "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" ] }, "client_secret": { "description": "The credential the buyer's surface presents to poll this setup intent and set its return URL. Returned when the setup is created and still has something to finish — hold on to it, because a later read will not repeat it. Null when the setup settled on the spot and there is nothing left to authorize. It unlocks this setup intent and nothing else; treat it like a password for that one attempt.", "example": "sint_xxxxxxxxxxxxxx_secret_v1_xxxx", "type": [ "string", "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." }, "three_ds_verified": { "description": "Whether 3D Secure authentication was completed when this payment method was set up.", "type": "boolean" } }, "required": [ "id", "status", "created_at", "error_message", "company", "checkout_configuration", "member", "payment_method", "metadata", "three_ds_verified", "client_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" }, "429": { "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": "Too many requests" }, "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", "member:basic:read", "member:email:read" ] } ], "summary": "Create setup intent", "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" }, "429": { "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": "Too many requests" }, "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" } }, "/setup_intents/{setup_intent_id}/return_url": { "patch": { "description": "Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the setup's own `client_secret`, so the surface that knows the final destination can set it.", "operationId": "updateReturnUrlSetupIntent", "parameters": [ { "description": "The unique identifier of the setup intent.", "in": "path", "name": "setup_intent_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters.", "example": "https://shinetime.example/checkout/thanks", "type": "string" } }, "required": [ "return_url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStatus" } } }, "description": "Return URL updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid return URL" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update setup return URL", "tags": [ "Setup Intents" ] }, "x-whop-surface": "native" }, "/setup_intents/{setup_intent_id}/status": { "get": { "description": "Retrieves how far a setup has got and what the buyer must do next, if anything. Collection runs in the background, so poll this rather than reading the create response. Accepts either a secret key or the setup's own `client_secret`, so the surface collecting the payment method can poll it directly.", "operationId": "retrieveStatusSetupIntent", "parameters": [ { "description": "The unique identifier of the setup intent.", "in": "path", "name": "setup_intent_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStatus" } } }, "description": "Setup status retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Setup intent not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve setup status", "tags": [ "Setup Intents" ] }, "x-whop-surface": "native" }, "/shipments": { "get": { "description": "Returns a paginated list of shipments for an account.", "operationId": "listShipments", "parameters": [ { "description": "The account to list shipments for. Defaults to the acting account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to shipments with this delivery status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "type": "string" } }, { "description": "Only shipments fulfilling these payments, each prefixed `pay_`. Repeat the parameter to pass several, up to 100 per request — one paginated list covers all of them.", "explode": true, "in": "query", "name": "payment_id", "required": false, "schema": { "items": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Return shipments created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Return shipments created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The number of shipments to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns shipments after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of shipments to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns shipments before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Shipment" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "excludes the created_after boundary row" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" } }, "security": [ { "bearerAuth": [ "shipment:basic:read" ] } ], "summary": "List Shipments", "tags": [ "Shipments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Attaches a carrier tracking number to a payment and begins tracking it.", "operationId": "createShipment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "payment_id": { "description": "The payment to attach the shipment to, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "tracking_number": { "description": "The carrier-assigned tracking number.", "example": "1Z999AA10123456784", "type": "string" } }, "required": [ "payment_id", "tracking_number" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "shipment created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing tracking_number" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "shipment:create" ] } ], "summary": "Create Shipment", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "/shipments/{id}": { "get": { "description": "Retrieves a shipment by its id, or by the payment id it fulfills.", "operationId": "retrieveShipment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "shipment retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "shipment not found" } }, "security": [ { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [] } ], "summary": "Retrieve Shipment", "tags": [ "Shipments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The shipment id (`ship_`), or the payment id (`pay_`) it fulfills.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a shipment's tracking number and re-tracks it with the carrier.", "operationId": "updateShipment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "tracking_number": { "description": "The new carrier-assigned tracking number.", "example": "9400111899223456789012", "type": "string" } }, "required": [ "tracking_number" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "shipment updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing tracking_number" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "shipment not found" } }, "security": [ { "bearerAuth": [ "shipment:create" ] } ], "summary": "Update Shipment", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "/social_accounts": { "get": { "description": "Lists the social accounts linked to an account or user.", "operationId": "listSocialAccounts", "parameters": [ { "description": "The Account that the social accounts are connected to. Provide either this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The User that the social accounts are connected to. Provide either this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return social accounts for the platform that is specified.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram" ], "type": "string" } }, { "description": "Only return social accounts that are verified on the platform.", "in": "query", "name": "verified", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return social accounts that have these scopes.", "in": "query", "name": "scopes", "required": false, "schema": { "items": { "enum": [ "advertise" ], "type": "string" }, "type": "array" } }, { "description": "The number of social accounts to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of social accounts to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort social accounts by.", "in": "query", "name": "order", "required": false, "schema": { "default": "display_order", "enum": [ "display_order", "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "asc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccount" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "filtered to accounts holding the requested scope" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither account_id nor user_id resolvable" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Accounts", "tags": [ "Social Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates or returns a Whop-managed Facebook page for an account.", "operationId": "createSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to create the social account for. An account-scoped API key may omit this to default to its own account. Account API keys cannot update their own account's branding through Update Account; use a user-authenticated path.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The platform to create the social account on. `facebook` requires the account's `banner_image`, `logo`, and `description`; configure them with [Update Account](/api-reference/beta/accounts/update-account).", "enum": [ "facebook" ], "example": "facebook", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccount" } } }, "description": "social account created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the account is missing the banner_image, logo, or description a Facebook page requires" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Create a Social Account", "tags": [ "Social Accounts" ] }, "x-whop-surface": "native" }, "/social_accounts/connect": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts an OAuth connection flow and returns an authorize_url where the user can connect a social account.", "operationId": "connectSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to connect the social account for. An account-scoped API key may omit this to default to its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The platform to connect the social account on. Use `meta_business` to connect Meta Business assets, which is how Facebook Pages and Instagram accounts are connected — there is no separate `instagram` value. Use `tiktok` for TikTok accounts.", "enum": [ "meta_business", "tiktok" ], "example": "meta_business", "type": "string" }, "redirect_url": { "description": "The Whop URL the user is sent to after Whop has processed the platform's OAuth callback. This is not the OAuth `redirect_uri` — the returned `authorize_url` always points at Whop's own callback endpoint, so expect the `redirect_uri` inside it to differ from this value.", "example": "https://whop.com/core/api/callback/meta/", "type": "string" }, "scopes": { "description": "Capabilities to grant for the connected social account. `advertise` is required for both `meta_business` and `tiktok` connections — it is not conditional on whether you intend to run ads, and omitting it fails the request.", "items": { "enum": [ "advertise" ], "example": "advertise", "type": "string" }, "type": "array" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "authorize_url": { "description": "The OAuth authorization URL to redirect the user to.", "example": "https://www.facebook.com/v25.0/dialog/oauth", "type": "string" } }, "required": [ "authorize_url" ], "type": "object" } } }, "description": "authorize url returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unsupported platform" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Connect a Social Account", "tags": [ "Social Accounts" ] }, "x-whop-surface": "native" }, "/social_accounts/{id}": { "delete": { "description": "Disconnects a social account from an account or user without deleting the underlying platform account.", "operationId": "deleteSocialAccount", "parameters": [ { "description": "The Account that the social account is connected to. Provide either this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The User that the social account is connected to. Provide either this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the disconnected social account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "user social account disconnected" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id and user_id both provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks delete permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "link already disconnected" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the social account is the parent of others that are still connected" } }, "security": [ { "bearerAuth": [ "social_account:delete" ] } ], "summary": "Delete a Social Account", "tags": [ "Social Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the social account to disconnect.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/social_accounts/{id}/lead_forms": { "get": { "description": "Lists the active lead (instant) forms that already exist on a connected Facebook page, so an ad can reuse one as its `lead_gen_form_id` instead of authoring a new form. Every active form comes back in a single response — the list is not paginated.", "operationId": "listSocialAccountLeadForms", "parameters": [ { "description": "The Account (a biz_ identifier) the social account is connected to.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccountLeadForm" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "lead forms listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id is missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "social account is not linked to the account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Lead Forms", "tags": [ "Social Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The social account (a sacc_ identifier) whose lead forms to list.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/social_accounts/{id}/posts": { "get": { "description": "Lists the existing posts of a connected Facebook page, Instagram account, or TikTok account.", "operationId": "listSocialAccountPosts", "parameters": [ { "description": "The Account (a biz_ identifier) the social account is connected to.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Return only the single post with this platform id, instead of the full list.", "in": "query", "name": "post_id", "required": false, "schema": { "type": "string" } }, { "description": "The number of posts to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccountPost" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "MTI=", "nullable": true, "type": "string" }, "has_next_page": { "example": true, "type": "boolean" } }, "required": [ "has_next_page", "end_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "single post returned when post_id is given" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the requested post is unavailable on the platform" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "social account is not linked to the account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Posts", "tags": [ "Social Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The social account (a sacc_ identifier) whose posts to list.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/stats": { "get": { "description": "Lists every metric you can query, with its unit and the properties you can filter or break it down by.", "operationId": "listMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "The available metrics.", "items": { "properties": { "description": { "description": "A short description of what the metric measures.", "example": "Share of paid receipts in the selected sales cohort disputed within 14 days of purchase.", "type": "string" }, "key": { "description": "The metric's key. Pass it to GET /stats/{metric} to query its values.", "example": "snapshot_cohorted_dispute_rate_14d_attr", "type": "string" }, "name": { "description": "Human-readable display name for the metric.", "example": "Cohorted dispute rate (14-day attribution)", "type": "string" }, "properties": { "description": "The properties you can use with this metric — pass one as a filter (property=value) to narrow the series, or as breakdown_by=property to split it.", "items": { "example": "source", "type": "string" }, "type": "array" }, "unit": { "description": "How to read the metric's values: count is an integer, currency is a decimal amount, and percent is a number where 1.6 means 1.6%.", "enum": [ "count", "currency", "percent" ], "example": "percent", "type": "string" }, "windows": { "description": "Snapshot metrics only: the trailing windows you can pass as snapshot_window, for example 30d. Absent on live metrics, which use from/to instead.", "items": { "example": "7d", "type": "string" }, "type": "array" } }, "required": [ "key", "name", "unit", "properties", "description" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "metric catalog" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Metrics", "tags": [ "Stats" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/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" }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "filters", "required": false, "schema": { "additionalProperties": true, "description": "Key-value pairs to filter the data.", "type": "object" }, "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" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "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" }, "429": { "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": "Too many requests" }, "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "limit", "required": false, "schema": { "description": "Number of records to return (max 10000).", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "cursor", "required": false, "schema": { "description": "Pagination cursor for next page.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "sort", "required": false, "schema": { "description": "Column to sort by.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "sort_direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "Sort direction (asc or desc)." }, "style": "form" }, { "explode": true, "in": "query", "name": "company_id", "required": false, "schema": { "description": "Scope query to a specific company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Scope query to a specific user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "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" }, "429": { "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": "Too many requests" }, "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/{metric}": { "get": { "description": "Retrieves a metric as a time series of points for an account or user over a time range. The `market_prices` metric is public and requires no authentication.", "operationId": "retrieveMetric", "parameters": [ { "description": "The account this query concerns, for example biz_AbC123.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The user this query concerns, for example user_AbC123. Available on metrics that support user subjects, such as account_balance.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the range — a date (YYYY-MM-DD), expanded to the start of that day, or an ISO 8601 timestamp (for example 2026-07-16T16:37:00Z), used exactly.", "in": "query", "name": "from", "required": true, "schema": { "type": "string" } }, { "description": "End of the range — a date (YYYY-MM-DD), expanded to the end of that day, or an ISO 8601 timestamp (for example 2026-07-17T16:37:00Z), used exactly.", "in": "query", "name": "to", "required": true, "schema": { "type": "string" } }, { "description": "How wide each point is. Defaults to day. Snapshot metrics are day-only.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "minute", "five_minutes", "thirty_minutes", "hour", "day", "week", "month", "year" ], "type": "string" } }, { "description": "Split the metric out by one of its properties — each point gets a breakdown array. For example breakdown_by=currency returns an entry for usd, an entry for eur, and so on.", "in": "query", "name": "breakdown_by", "required": false, "schema": { "type": "string" } }, { "description": "Display currency for money metrics — every amount is converted into this ISO currency using the exchange rate on each period's date. Defaults to usd. For the ads metrics (ad_spend, ad_delivery), pass the account's ads reporting currency to match the ad entity endpoints. On transaction metrics, it is ignored when you filter or break down by currency (those report the original transaction currency, unconverted).", "in": "query", "name": "convert_to", "required": false, "schema": { "type": "string" } }, { "description": "Select the source currency or asset on metrics that list currency. For transaction metrics, for example currency=eur, values are reported without conversion. For market_prices, use btc or xaut and convert_to=usd. Pair with breakdown_by=currency to split a metric by currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "IANA time zone to bucket the series in, for example America/New_York. Defaults to UTC. Not accepted by snapshot metrics, which are UTC only.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single payment method, for example card or crypto. Available on metrics that list payment_method.", "in": "query", "name": "payment_method", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single card brand, for example visa. A refinement of payment_method=card. Available on metrics that list card_network.", "in": "query", "name": "card_network", "required": false, "schema": { "type": "string" } }, { "description": "Filter disputes to a normalized reason, for example product_not_received. Pair with breakdown_by=dispute_reason to split dispute counts by reason.", "in": "query", "name": "dispute_reason", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single GMV source, for example payments — or, on the traffic metrics, a visit source (whop_ads, direct, or a utm_source value). Pair with breakdown_by=source to split by source. Available on metrics that list source.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one website hostname, for example shop.example.com. Pair with breakdown_by=hostname to split by website.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one page — a hostname plus normalized path, for example shop.example.com/pricing. Pair with breakdown_by=page to split by page.", "in": "query", "name": "page", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one device type: desktop, mobile, tablet, or unknown. Pair with breakdown_by=device_type to split by device.", "in": "query", "name": "device_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one visitor country (uppercase ISO 3166-1 alpha-2, for example US). Pair with breakdown_by=country_code to split by country.", "in": "query", "name": "country_code", "required": false, "schema": { "type": "string" } }, { "description": "Filter the events metric to one tracked event name, for example pixel.page or pixel.custom. Pair with breakdown_by=event_name to split by event.", "in": "query", "name": "event_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter the events metric to a canonical group of events: page_view (pixel page views plus whop.com store views), checkout_start (hosted and embedded checkout views), or other. Pair with breakdown_by=event_type to split by group.", "in": "query", "name": "event_type", "required": false, "schema": { "enum": [ "page_view", "checkout_start", "other" ], "type": "string" } }, { "description": "Filter the events metric to one merchant-defined custom event name. Only valid alongside event_name=pixel.custom. Pair with breakdown_by=custom_name to split custom events by name.", "in": "query", "name": "custom_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single wallet-balance segment, for example available. Pair with breakdown_by=segment to split the balance. Available on metrics that list segment.", "in": "query", "name": "segment", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single balance-activity category, for example payments. Pair with breakdown_by=category to split the activity. Available on metrics that list category.", "in": "query", "name": "category", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single cashback merchant bucket, for example whop-ads. Pair with breakdown_by=merchant to split cashback by merchant. Available on metrics that list merchant.", "in": "query", "name": "merchant", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single fee type. Pair with breakdown_by=fee_type to split fees by type. Available on metrics that list fee_type.", "in": "query", "name": "fee_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single product (access pass id), for example prod_AbC123. Pair with breakdown_by=product. Available on metrics that list product.", "in": "query", "name": "product", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single membership status. Pair with breakdown_by=status. Available on metrics that list status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single access level. Pair with breakdown_by=access_level. Available on metrics that list access_level.", "in": "query", "name": "access_level", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single most-recent member action. Pair with breakdown_by=most_recent_action. Available on metrics that list most_recent_action.", "in": "query", "name": "most_recent_action", "required": false, "schema": { "type": "string" } }, { "description": "Filter a referral metric to the businesses attributed to one person you referred, for example user_AbC123. Available on metrics that list referred_user_id.", "in": "query", "name": "referred_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Ad campaign ids (adcamp_...) to scope the report to; stats are summed across them. Available on metrics that list ad_campaign_ids.", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Ad group ids (adgrp_...) to scope the report to; stats are summed across them. Available on metrics that list ad_group_ids.", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "items": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Ad ids (ad_...) to scope the report to; stats are summed across them. Available on metrics that list ad_ids.", "in": "query", "name": "ad_ids", "required": false, "schema": { "items": { "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Window used by a snapshot metric. Ordinary snapshots accept 30d as their trailing activity window. Cohorted dispute metrics accept 7d or 28d as the sales-transaction pool; their attribution window is fixed in the metric name. Each metric lists its accepted values in the catalog.", "in": "query", "name": "snapshot_window", "required": false, "schema": { "enum": [ "7d", "28d", "30d" ], "type": "string" } }, { "description": "Filter the events metric to one or more full event names, for example payment.completed or pixel.lead. Comma-separate several to break the metric down by each event. Available on metrics that list event.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "currency": { "description": "ISO currency the values are denominated in. Present for currency-unit metrics: the convert_to currency, or usd.", "example": "usd", "nullable": true, "type": "string" }, "points": { "description": "One entry per period, oldest first.", "items": { "properties": { "breakdown": { "description": "Present only when broken down: one entry per property value in this period.", "items": { "properties": { "name": { "description": "The property value, for example usd or visa.", "example": "spend", "type": "string" }, "value": { "description": "The metric's value for this entry.", "example": 2.82, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "timestamp": { "description": "Unix timestamp (seconds) of the period start.", "example": 1767268800, "type": "integer" }, "value": { "description": "The metric's value for this period, in the metric's unit.", "example": 5, "nullable": true, "type": "number" } }, "required": [ "timestamp", "value" ], "type": "object" }, "type": "array" }, "totals": { "description": "Whole-window aggregates, present when the metric computes them. Don't derive these from `points`: a rate is measured across the whole window, not averaged across its points, and unique-people counts exist only at window level.", "items": { "properties": { "name": { "description": "The property value this total is for, or the metric's name when it isn't split by a property.", "example": "spend", "type": "string" }, "value": { "description": "The metric's whole-window value for this entry.", "example": 2.82, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "nullable": true, "type": "array" } }, "required": [ "points" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "a user-scoped metric via a scoped OAuth token" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "subject tag type mismatch" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication for an account-scoped metric" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "a user-scoped metric with a credential that cannot act as a user" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" } }, "security": [ { "bearerAuth": [ "stats:read" ] }, { "bearerAuth": [ "ad_campaign:read" ] } ], "summary": "Retrieve Metric", "tags": [ "Stats" ] }, "parameters": [ { "description": "The metric to retrieve, for example net_revenue. Use GET /stats to see every metric key. The metric sets the unit and the properties you can filter or break down by.", "in": "path", "name": "metric", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "view", "required": false, "schema": { "$ref": "#/components/schemas/SupportChannelView", "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." }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for the results. Use 'asc' for oldest first or 'desc' for newest first." }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/MessageChannelOrder", "description": "The field to sort the support channels by, such as creation date or last message time." }, "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" }, "429": { "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": "Too many requests" }, "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" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this support channel. Webhooks still fire.", "type": [ "boolean", "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" }, "429": { "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": "Too many requests" }, "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" }, "429": { "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": "Too many requests" }, "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": "Retrieve the account's completed or pending swaps — currently just the latest one.", "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": { "description": "Swaps returned for this account.", "items": { "properties": { "account_id": { "description": "Account ID that owns the wallet used for the swap.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "error": { "description": "Latest error returned for a failed swap.", "example": "Swap reverted: quoted price moved beyond the slippage tolerance", "type": [ "string", "null" ] }, "id": { "description": "Swap ID.", "example": "vault-swap-cwal_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "swap" ], "example": "swap", "type": "string" }, "status": { "description": "Current swap status. `complete` and `failed` are terminal.", "enum": [ "queued", "working", "complete", "failed" ], "example": "working", "type": "string" }, "tx_hashes": { "description": "On-chain transaction hashes produced by the swap.", "items": { "example": "0xabc", "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:swap" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "List Swaps", "tags": [ "Swaps" ] }, "post": { "description": "Swaps one token for another from the account's wallet, or converts between fiat currencies in the account's ledger at the mid-market rate. Crypto swaps finish in the background — check the swap for its status.", "operationId": "createSwap", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Business or user account ID (biz_* / user_*).", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "Source token amount. Required for crypto swaps. For fiat pairs: the amount of from_token to convert at the mid-market rate; omit (along with to_amount) to repay the full negative to_token balance instead.", "example": "100", "type": [ "string", "null" ] }, "from_chain": { "description": "Source chain name or chain ID. Defaults to the source token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "from_token": { "description": "Source token contract address or ticker symbol, such as \"USDT\".", "example": "usd", "type": "string" }, "slippage_bps": { "description": "Maximum slippage tolerance in basis points.", "example": 50, "type": [ "integer", "null" ] }, "to_amount": { "description": "Fiat pairs only: sizes a partial repayment of the negative to_token balance, denominated in to_token. Must not exceed the debt. Mutually exclusive with amount.", "example": "180.00", "type": [ "string", "null" ] }, "to_chain": { "description": "Destination chain name or chain ID. Defaults to the destination token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "to_token": { "description": "Destination token contract address or ticker symbol, such as \"XAUT\".", "example": "cad", "type": "string" } }, "required": [ "account_id", "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID that owns the wallet used for the swap.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount_in": { "description": "Fiat pairs only: amount of the source currency converted. Null while a stablecoin repayment is processing.", "example": 131.4, "type": [ "number", "null" ] }, "amount_out": { "description": "Fiat pairs only: amount credited in the destination currency. Null while a stablecoin repayment is processing.", "example": 180.0, "type": [ "number", "null" ] }, "amount_out_expected": { "description": "Expected destination token amount.", "example": "98.9", "type": "string" }, "amount_out_min": { "description": "Minimum destination amount after slippage.", "example": "98.4", "type": "string" }, "from_token": { "description": "Fiat pairs only: the source currency.", "properties": { "symbol": { "example": "usd", "type": "string" } }, "type": [ "object", "null" ] }, "id": { "description": "Swap ID. Poll `GET /swaps/:id` for status.", "example": "vault-swap-cwal_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "swap" ], "example": "swap", "type": "string" }, "rate": { "description": "Quoted exchange rate used to create the swap.", "example": "0.989", "type": "string" }, "status": { "description": "Swap status. Crypto swaps start `queued`; fiat conversions return `complete`, or `working` while a stablecoin repayment settles.", "enum": [ "queued", "working", "complete", "failed" ], "example": "queued", "type": "string" }, "to_chain": { "description": "Destination chain for the swap.", "example": "ethereum", "type": "string" }, "to_token": { "description": "Fiat pairs only: the destination currency.", "properties": { "symbol": { "example": "cad", "type": "string" } }, "type": [ "object", "null" ] } }, "required": [ "object", "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" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "crypto_wallet:swap" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] }, { "bearerAuth": [ "payout:transfer_funds" ] } ], "summary": "Create Swap", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "/swaps/quote": { "post": { "description": "Previews the price of a swap. Fiat pairs quote the in-ledger mid-market conversion — the same rate creating the swap fills at. No funds move and nothing is saved.", "operationId": "createSwapQuote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Source token amount.", "example": "100", "type": "string" }, "from_address": { "description": "Source wallet address used for the quote.", "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": [ "string", "null" ] }, "from_chain": { "description": "Source chain name or chain ID. Defaults to the source token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "from_token": { "description": "Source token contract address or ticker symbol, such as \"USDT\".", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Metadata to include with the quote response.", "example": { "external_id": "shop_4417" }, "type": "object" }, "slippage_bps": { "description": "Maximum slippage tolerance in basis points.", "example": 50, "type": [ "integer", "null" ] }, "to_address": { "description": "Destination wallet address used for the quote.", "example": "0x9d2e4b6a806f1c0a3d5b2e4f8a9c7d1e0b3a5f7c", "type": [ "string", "null" ] }, "to_chain": { "description": "Destination chain name or chain ID. Defaults to the destination token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "to_token": { "description": "Destination token contract address or ticker symbol, such as \"XAUT\".", "example": "0x1b64b9025eebb9a6239575df9ea4b9ac46d4d193", "type": "string" } }, "required": [ "amount", "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount_in": { "description": "Source token amount used for the quote.", "example": "100", "type": "string" }, "amount_out": { "description": "Estimated destination token amount.", "example": "0.15", "type": "string" }, "amount_out_min": { "description": "Minimum destination amount after slippage.", "example": "0.148", "type": "string" }, "bridge_fee": { "description": "Estimated bridge fee for cross-chain swaps.", "example": "0.25", "type": [ "string", "null" ] }, "estimated_duration_seconds": { "description": "Estimated time for the swap to complete.", "example": 30, "type": [ "integer", "null" ] }, "fee_bps": { "description": "Whop fee in basis points.", "example": 100, "type": "integer" }, "from_address": { "description": "Source wallet address used for the quote.", "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": [ "string", "null" ] }, "from_token": { "additionalProperties": true, "description": "Resolved source token details.", "example": { "address": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "chain_id": 9745, "decimals": 6, "network": "plasma", "symbol": "USDT" }, "type": "object" }, "metadata": { "additionalProperties": true, "description": "Metadata from the request.", "example": { "external_id": "shop_4417" }, "type": "object" }, "object": { "enum": [ "swap_quote" ], "example": "swap_quote", "type": "string" }, "rate": { "description": "Quoted exchange rate.", "example": "1.5", "type": "string" }, "requires_token_approval": { "description": "Whether the source token needs approval before swapping.", "example": true, "type": [ "boolean", "null" ] }, "to_address": { "description": "Destination wallet address used for the quote.", "example": "0x9d2e4b6a806f1c0a3d5b2e4f8a9c7d1e0b3a5f7c", "type": [ "string", "null" ] }, "to_token": { "additionalProperties": true, "description": "Resolved destination token details.", "example": { "address": "0x1b64b9025eebb9a6239575df9ea4b9ac46d4d193", "chain_id": 9745, "decimals": 6, "network": "plasma", "symbol": "XAUT" }, "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" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [], "summary": "Create Swap Quote", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "/swaps/{id}": { "get": { "description": "Retrieves a single swap and its status.", "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": { "description": "Account ID that owns the wallet used for the swap.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "error": { "description": "Latest error returned for a failed swap.", "example": "Swap reverted: quoted price moved beyond the slippage tolerance", "type": [ "string", "null" ] }, "id": { "description": "Swap ID.", "example": "vault-swap-cwal_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "swap" ], "example": "swap", "type": "string" }, "status": { "description": "Current swap status. `complete` and `failed` are terminal.", "enum": [ "queued", "working", "complete", "failed" ], "example": "failed", "type": "string" }, "tx_hashes": { "description": "On-chain transaction hashes produced by the swap.", "items": { "example": "0xabc", "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:swap" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "Retrieve Swap", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "/team_members": { "get": { "description": "Lists an account's team members, including pending invites (`status: \"pending\"`, `ausri_` ids; `user` is `null` for invites sent to an email with no Whop account yet). For accepted members, `email` requires the `company:authorized_user:email:read` scope and is `null` otherwise. Listing `role=workforce` is also allowed with the `bounty:create` scope.", "operationId": "listTeamMembers", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Only return members with this status: `joined` (accepted members) or `pending` (pending invites). Both are returned by default.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "joined", "pending" ], "type": "string" } }, { "description": "Only return the membership for this user ID, prefixed `user_`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return members with this role. `custom` matches members on a dashboard-managed custom role.", "in": "query", "name": "role", "required": false, "schema": { "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "type": "string" } }, { "description": "Only return members added before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return members added after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Field used to sort members.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of members to return. Defaults to 20; maximum 100.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for the next page of members.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of members to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TeamMember" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "Mw", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Team members listed." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid filter." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Missing the required scope." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Account not found." } }, "security": [ { "bearerAuth": [ "company:authorized_user:read" ] } ], "summary": "List Team Members", "tags": [ "Team Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Adds a member to an account's team with a system role. Identify them by exactly one of `user_id` or `email`. If the person has not yet accepted — or the email does not belong to a Whop account yet — an invitation is sent instead and the response is `202` with `{ \"object\": \"team_member_invite\", \"invitation_sent\": true }`. If they already have a pending invite, the request fails with a `400`. Custom roles cannot be granted via the API. Granting the `workforce` role is also allowed with the `bounty:create` scope.", "operationId": "createTeamMember", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "email": { "description": "Email address to invite. Mutually exclusive with `user_id`. If the email already belongs to a Whop account it is treated the same as passing that account's `user_id`; otherwise a pending invite is created for the email.", "example": "marcus@shinetime.example", "type": "string" }, "role": { "description": "The system role to grant.", "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser", "workforce" ], "example": "sales_manager", "type": "string" }, "user_id": { "description": "The user to add to the team, prefixed `user_`. Mutually exclusive with `email`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id", "role" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member created." }, "202": { "content": { "application/json": { "schema": { "properties": { "invitation_sent": { "example": true, "type": "boolean" }, "object": { "enum": [ "team_member_invite" ], "example": "team_member_invite", "type": "string" } }, "required": [ "object", "invitation_sent" ], "type": "object" } } }, "description": "Invitation sent — the user must accept before they join the team." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid request." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "authorized_user:create" ] } ], "summary": "Create Team Member", "tags": [ "Team Members" ] }, "x-whop-surface": "native" }, "/team_members/{id}": { "delete": { "description": "Removes a team member from the account, or revokes a pending invite when given an `ausri_` ID. A user session may delete its own membership to leave the team without the delete scope. Removing a member on the `workforce` role is also allowed with the `bounty:create` scope. The account owner cannot be removed.", "operationId": "deleteTeamMember", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Team member removed." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid request." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Not allowed to remove this member." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Team member not found." } }, "security": [ { "bearerAuth": [ "authorized_user:delete" ] } ], "summary": "Delete Team Member", "tags": [ "Team Members" ] }, "get": { "description": "Retrieves a team member by ID. `email` requires the `company:authorized_user:email:read` scope and is `null` otherwise.", "operationId": "retrieveTeamMember", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member retrieved." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Team member not found." } }, "security": [ { "bearerAuth": [ "company:authorized_user:read" ] } ], "summary": "Retrieve Team Member", "tags": [ "Team Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Team member ID — `ausr_` for accepted members, `ausri_` for pending invites.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Changes a team member's system role. Requires a user session — account API keys cannot change member roles. The account owner's role cannot be changed, and you cannot change your own role.", "operationId": "updateTeamMember", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "role": { "description": "The system role to grant.", "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser", "workforce" ], "example": "workforce", "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member updated." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid request." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Team member not found." } }, "security": [ { "bearerAuth": [ "authorized_user:update" ] } ], "summary": "Update Team Member", "tags": [ "Team Members" ] }, "x-whop-surface": "native" }, "/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" }, "429": { "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": "Too many requests" }, "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": "Lists an account's transfers.", "operationId": "listTransfer", "parameters": [ { "description": "Filter to transfers sent from this account. Provide this or destination_id.", "in": "query", "name": "origin_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to transfers received by this account. Provide this or origin_id.", "in": "query", "name": "destination_id", "required": false, "schema": { "type": "string" } }, { "description": "Sort column. Defaults to created_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "amount" ], "type": "string" } }, { "description": "Sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only transfers created strictly before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only transfers created strictly after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Number of transfers to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 50, "maximum": 50, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of transfers to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 50, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25.0, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "null" ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user" ], "title": "TransferListItem", "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page", "start_cursor", "end_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "transfers listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither origin_id nor destination_id given" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "List Transfers", "tags": [ "Transfers" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Moves money between accounts, or into a claim link anyone with the URL can redeem.", "operationId": "createTransfer", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The amount to move, in the transfer currency. For example 25.00.", "example": 25.0, "type": "number" }, "currency": { "description": "Currency, such as `usd`. Required for ledger transfers.", "example": "usd", "type": "string" }, "destination_id": { "description": "The recipient. Required for ledger and wallet_send (a user_/biz_/ldgr_ ID, or — for sends — an email). Omit for claim_link.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "expires_at": { "description": "claim_link only. Link expiry as an ISO 8601 timestamp. Defaults to 24 hours from creation.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "idempotence_key": { "description": "Ledger transfers and wallet sends. A unique key that makes retries safe. Retrying with the same key returns the original transfer, or attaches to the original wallet send, instead of moving money twice.", "example": "shine-supplies-restock-118", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Ledger transfers only. Custom key-value pairs attached to the transfer. Max 50 keys, 100 chars per key, 500 chars per string value.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Ledger transfers only. A short note describing the transfer.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "origin_id": { "description": "The account sending the funds. A user ID (user_xxx), account ID (biz_xxx), or ledger account ID (ldgr_xxx).", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "redeemable_count": { "description": "claim_link only. How many different users can claim the link. Defaults to 1.", "example": 3, "type": "integer" }, "type": { "description": "The kind of money movement, which decides what comes back. Defaults to ledger. `ledger` moves credit between two Whop balances and returns a `transfer`; `wallet_send` sends USDT from the origin account's Ethereum wallet and returns a `send`; `claim_link` funds a shareable link anyone with the URL can redeem and returns a `claim_link`. A `ledger` transfer from a stablecoin-rails account settles on-chain when covered, and still returns a `transfer`.", "enum": [ "ledger", "wallet_send", "claim_link" ], "example": "wallet_send", "type": "string" } }, "required": [ "origin_id", "amount" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25.0, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "null" ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "title": "Transfer", "type": "object" }, { "description": "Returned for a wallet_send: an onchain USDT send to a recipient.", "properties": { "amount": { "example": "25.00", "type": "string" }, "currency": { "example": "usdt", "type": "string" }, "destination": { "properties": { "account_id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "address": { "example": "0x9d2e4b6a806f1c0a3d5b2e4f8a9c7d1e0b3a5f7c", "type": "string" } }, "required": [ "account_id", "address" ], "type": "object" }, "object": { "enum": [ "send" ], "example": "send", "type": "string" }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "address": { "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": "string" } }, "required": [ "account_id", "address" ], "type": "object" }, "tx_hash": { "example": "0x4a7d1ed414474e4033ac29ccb8653d9bd1d3f0b2c9b0f7a4d6e8c0a2b4d6f8a0", "type": "string" } }, "required": [ "object", "tx_hash", "amount", "currency", "source", "destination" ], "title": "Send", "type": "object" }, { "description": "Returned for a claim_link: a shareable URL anyone can open to claim the funds.", "properties": { "amount": { "example": "25.00", "type": "string" }, "claim_url": { "example": "https://whop.com/claim", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "expires_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "claim_link" ], "example": "claim_link", "type": "string" }, "redeemable_count": { "example": 3, "type": "integer" }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "status": { "description": "A newly funded claim link is always `pending` — it stays claimable until it is fully claimed, canceled, or expires.", "enum": [ "pending" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "claim_url", "status", "amount", "currency", "redeemable_count", "expires_at", "source" ], "title": "ClaimLink", "type": "object" } ] } } }, "description": "money movement 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 required scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:transfer_funds" ] }, { "bearerAuth": [ "payout:withdraw_funds" ] }, { "bearerAuth": [ "airdrop_link:manage" ] } ], "summary": "Create Transfer", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "/transfers/recipients": { "get": { "description": "Lists the people and accounts you can send money to.", "operationId": "listTransferRecipients", "parameters": [ { "description": "The account sending the money: a company account ID (`biz_`), or a user ID (`user_`) for that user's own personal balance.", "in": "query", "name": "origin_id", "required": true, "schema": { "type": "string" } }, { "description": "Search anyone on Whop by name or username, plus your own accounts by name or ID. An exact business ID (`biz_`) returns that business first. Omit it to get the team around the balance, the people you follow, and your own accounts. The list is the same whether the balance belongs to a company or to you. Searching from a `biz_` origin additionally requires the member:basic:read scope. A credential scoped to a single company is the exception to the search itself: it only ever sees that company's own people. Complete email addresses return no matches.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Number of recipients per page. Search queries preserve the dashboard's 20-result maximum.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "oneOf": [ { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "title": "TransferRecipientUser", "type": "object" }, { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "title": "TransferRecipientAccount", "type": "object" } ] }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "Mg", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "recipients listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "origin account is missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks a required scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "origin account not found" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds", "company:authorized_user:read" ] }, { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "List Transfer Recipients", "tags": [ "Transfers" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/transfers/{id}": { "get": { "description": "Retrieves a single transfer.", "operationId": "retrieveTransfer", "responses": { "200": { "content": { "application/json": { "schema": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25.0, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "null" ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "title": "Transfer", "type": "object" } } }, "description": "transfer retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "transfer not found" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "Retrieve Transfer", "tags": [ "Transfers" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The transfer ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/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": { "example": "MQ", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "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" } ], "x-whop-surface": "native" }, "/users/me": { "get": { "description": "Retrieves the authenticated user — the self view of the user object. Same shape as `GET /users/{id}`, with the self-only fields populated: `email` (email-read scope), `staff` (Whop staff only, staff-read scope), `balance` and `earnings_usd` (balance-read scope), the opt-in `balance_history`, and every linked social account.", "operationId": "retrieveCurrentUser", "parameters": [ { "description": "When set, returns your account-specific profile overrides for this account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Also compute your balance history (opt-in; runs a heavier query). Ignored for callers without balance-read scope.", "in": "query", "name": "include_balance_history", "required": false, "schema": { "type": "boolean" } }, { "description": "Balance-history window start, ISO 8601 date or datetime. Defaults to 30 days ago. Only used with `include_balance_history`.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history window end, ISO 8601 date or datetime. Defaults to now. Only used with `include_balance_history`.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history point granularity. Defaults to `day`. Only used with `include_balance_history`.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "description": "IANA time zone the balance-history points are bucketed in. Defaults to `UTC`. Only used with `include_balance_history`.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "current user retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve Current User", "tags": [ "Users" ], "x-whop-docs": "hidden" }, "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": { "banner": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "bio": { "example": "Interior specialist. Leather, upholstery, and odor removal.", "type": "string" }, "name": { "example": "Tanya Cole", "type": "string" }, "profile_picture": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "username": { "example": "tanyacole", "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" ], "x-whop-docs": "hidden" }, "x-whop-surface": "native" }, "/users/me/oauth_grants": { "get": { "description": "Lists the authenticated user's own OAuth grants — one per app they have authorized, per account they authorized it for. The list is always the caller's own; there is no parameter for reading another user's grants. Requires a user session: an API key or an OAuth token is refused, so an app can never enumerate the other apps a user has authorized.", "operationId": "listOauthGrants", "parameters": [ { "description": "Only return grants for this app, prefixed `app_`. An app the user has never authorized returns an empty list.", "in": "query", "name": "app_id", "required": false, "schema": { "type": "string" } }, { "description": "The number of grants to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns grants after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of grants to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns grants before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort grants by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OauthGrant" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "oauth grants listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" } }, "security": [ { "bearerAuth": [] } ], "summary": "List OAuth Grants", "tags": [ "Users" ], "x-whop-docs-subgroup": "OAuth Grants" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Completes the OAuth authorization step for the authenticated user: records their consent for the scopes an app asked for and mints the authorization code to hand back to it. Returns the grant, plus a `redirect_url` carrying that code — the one and only time it is returned. Exchange the code at `POST /oauth/token` with the verifier for `code_challenge`. Requires a user session, because consent has to come from the account holder: an API key or an OAuth token is refused, so an app can never authorize itself. Send an `Idempotency-Key` to make a retry safe — a replay returns the original `redirect_url` and its code rather than issuing a second one.", "operationId": "createOauthGrant", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Authorize the app for one of the user's accounts rather than for the user alone, prefixed `biz_`. The user must have access to it.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "client_id": { "description": "The app being authorized, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "code_challenge": { "description": "The PKCE code challenge: the base64url-encoded SHA-256 of your code verifier, without padding.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "code_challenge_method": { "description": "How `code_challenge` was derived. Only `S256` is accepted.", "enum": [ "S256" ], "example": "S256", "type": "string" }, "consent_shown": { "default": true, "description": "Whether the consent UI listed these scopes for the user. Sending `false` succeeds only when the user has already granted every scope requested.", "example": true, "type": "boolean" }, "nonce": { "description": "OIDC nonce, echoed into the resulting ID token. Required when `requested_scopes` includes `openid`.", "example": "n-0S6_WzA2Mj", "type": "string" }, "redirect_uri": { "description": "Where to send the user once they have consented. Must match one of the app's registered redirect URIs exactly — it is compared as a string, not normalized.", "example": "https://Booking.Shinetime.example:8443/oauth/Callback/", "type": "string" }, "requested_scopes": { "description": "The permissions the app is asking for, for example `member:basic:read`. `GET /api_keys/permissions` names and describes each one. Granting adds to whatever the user already granted this app rather than replacing it.", "items": { "example": "profile", "type": "string" }, "type": "array" }, "response_type": { "description": "The OAuth response type. Only `code` is accepted; defaults to `code`.", "enum": [ "code" ], "example": "code", "type": "string" }, "state": { "description": "Opaque value appended to `redirect_url` unchanged, for the client to correlate the response with its request.", "example": "opaque-client-state", "type": "string" } }, "required": [ "client_id", "redirect_uri", "requested_scopes", "code_challenge", "code_challenge_method" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthGrant" } } }, "description": "the app is authorized" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the account does not exist" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Authorize an App", "tags": [ "Users" ], "x-whop-docs-subgroup": "OAuth Grants" }, "x-whop-surface": "native" }, "/users/me/passkeys": { "get": { "description": "Lists the authenticated user's own passkeys, newest first. The list is always the caller's own; there is no parameter for reading another user's passkeys. Requires a user session: an API key or an OAuth token is refused, because a passkey confirms the account holder before a sensitive action and no app may enumerate one.", "operationId": "listPasskeys", "parameters": [ { "description": "The number of passkeys to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns passkeys after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of passkeys to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns passkeys before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort passkeys by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Passkey" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "passkeys listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" } }, "security": [ { "bearerAuth": [] } ], "summary": "List", "tags": [ "Users" ], "x-whop-docs-subgroup": "Passkeys" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Registers a passkey for the authenticated user from the attestation a browser produced for a `registration` challenge. Mint that challenge first with `POST /users/me/passkeys/challenge`; it is single-use and expires 5 minutes after it is issued. Requires a user session.", "operationId": "createPasskey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attestation_object": { "description": "The `attestationObject` from the WebAuthn attestation response, base64url-encoded.", "example": "YXR0ZXN0YXRpb24", "type": "string" }, "client_data_json": { "description": "The `clientDataJSON` from the WebAuthn attestation response, base64url-encoded.", "example": "Y2xpZW50LWRhdGE", "type": "string" }, "credential_id": { "description": "The WebAuthn credential ID the authenticator returned, base64url-encoded.", "example": "bmV3LWNyZWRlbnRpYWw", "type": "string" }, "nickname": { "description": "A name for this passkey, usually the device it lives on. 255 characters or fewer.", "example": "Work laptop", "type": "string" } }, "required": [ "credential_id", "client_data_json", "attestation_object", "nickname" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkey" } } }, "description": "passkey registered" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Register", "tags": [ "Users" ], "x-whop-docs-subgroup": "Passkeys" }, "x-whop-surface": "native" }, "/users/me/passkeys/challenge": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Mints the challenge a browser needs to run a WebAuthn ceremony against the authenticated user's own passkeys. A `registration` challenge enrolls a new passkey; a `deletion` challenge is bound to the one passkey named by `passkey_id` and proves the user still holds it. Challenges are single-use and expire 5 minutes after they are issued, so send a fresh `Idempotency-Key` per ceremony — a replayed key returns the original challenge, which may already have expired. Requires a user session.", "operationId": "createPasskeyChallenge", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "challenge_type": { "description": "The ceremony this challenge is for.", "enum": [ "registration", "deletion" ], "example": "registration", "type": "string" }, "passkey_id": { "description": "The passkey the ceremony targets, prefixed `wcred_`. Required when `challenge_type` is `deletion`, ignored otherwise.", "example": "wcred_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "challenge_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "challenge": { "description": "The challenge to pass to the WebAuthn ceremony, base64url-encoded without padding.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "challenge" ], "type": "object" } } }, "description": "challenge minted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the passkey is not the caller's own" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Challenge", "tags": [ "Users" ], "x-whop-docs-subgroup": "Passkeys" }, "x-whop-surface": "native" }, "/users/me/passkeys/{id}": { "delete": { "description": "Deletes one of the authenticated user's own passkeys. The request body carries a WebAuthn assertion from the passkey being deleted, so possession of the credential is proven before it is removed: mint a `deletion` challenge for it first, run the ceremony with that passkey, and send the result here. Deleting the user's last passkey is allowed — their other step-up factors remain. Requires a user session.", "operationId": "deletePasskey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authenticator_data": { "description": "The `authenticatorData` from the WebAuthn assertion, base64url-encoded.", "example": "YXV0aGVudGljYXRvci1kYXRh", "type": "string" }, "client_data_json": { "description": "The `clientDataJSON` from the WebAuthn assertion, base64url-encoded.", "example": "Y2xpZW50LWRhdGE", "type": "string" }, "signature": { "description": "The `signature` from the WebAuthn assertion, base64url-encoded.", "example": "c2lnbmF0dXJl", "type": "string" } }, "required": [ "client_data_json", "authenticator_data", "signature" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`: the passkey was removed.", "example": true, "type": "boolean" }, "id": { "description": "The ID of the deleted passkey.", "example": "wcred_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "passkey deleted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the passkey is not the caller's own" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete", "tags": [ "Users" ], "x-whop-docs-subgroup": "Passkeys" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Passkey ID, prefixed `wcred_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/users/me/preferences": { "get": { "description": "Retrieves the authenticated user's settings document. Addressed only as `me` — the document always belongs to the session user.", "operationId": "retrieveUserPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferences" } } }, "description": "preferences retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Retrieve", "tags": [ "Users" ], "x-whop-docs-subgroup": "Preferences" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates the authenticated user's settings document. Replaces the top-level keys it is given and leaves the rest untouched.", "operationId": "updateUserPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bounty_worker_onboarding_dismissed": { "description": "Whether the user has dismissed the first-time bounty worker onboarding. Set to `false` to show it again.", "example": true, "type": "boolean" }, "investigation_enabled": { "description": "Whether investigation mode is enabled for the user. Only meaningful for staff users with investigation access.", "example": false, "type": "boolean" }, "terms_accepted": { "description": "Records the user's acceptance of Whop's terms and policies. Only `true` is accepted — the server stamps `terms_accepted_at` and acceptance cannot be withdrawn here.", "example": true, "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferences" } } }, "description": "preferences updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unsupported preference key" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Update", "tags": [ "Users" ], "x-whop-docs-subgroup": "Preferences" }, "x-whop-surface": "native" }, "/users/me/preferences/notifications": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Sets the authenticated user's notification preferences. Each preference is addressed by `scope`, not by id, so a scope read back from either list endpoint can be sent straight here.\n\nA scope naming an experience with no topic sets that experience's level, and accepts all three levels. Any other scope sets a topic override, which is binary — `all` or `nothing` — and requires a `channel`.\n\n`level: null` clears the preference. Preferences are stored as overrides, so clearing one means the scope inherits its default again rather than being switched off.\n\nThe batch is applied in one transaction: if any entry is rejected, none are written. Experience levels are applied before topic overrides, because setting a level replaces every topic preference for that experience — so an override sent alongside a level wins. The response reports what each scope now resolves to, in the order the entries were sent.", "operationId": "setUserNotificationPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "preferences": { "description": "The preferences to set, at most 100 per request.", "items": { "properties": { "level": { "description": "What the user is notified about in this scope. `mentions` is only valid for an experience level. `null` clears the preference.", "enum": [ "all", "mentions", "nothing", null ], "example": "nothing", "type": [ "string", "null" ] }, "scope": { "description": "What the preference applies to. `null` on a dimension means the preference is not narrowed there.", "properties": { "account_id": { "description": "Account to scope the preference to (member notifications), `biz_` tag.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "channel": { "description": "Delivery channel the preference applies to. Required when setting a topic override.", "enum": [ "in_app", "mobile", null ], "example": "in_app", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience to scope the preference to (`exp_` tag). Requires `account_id` when a `topic_id` is also given.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "team_account_id": { "description": "Account whose team notifications the preference is scoped to, `biz_` tag.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "topic_id": { "description": "Notification topic to scope the preference to, `topic_` tag.", "example": "topic_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "type": "object" } }, "required": [ "scope", "level" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "preferences" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationPreferenceState" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "preferences set" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "scope names nothing to scope to" }, "404": { "$ref": "#/components/responses/NotFound", "description": "scoped account does not exist" } }, "security": [ { "bearerAuth": [ "user:notifications:update" ] } ], "summary": "Set", "tags": [ "Users" ], "x-whop-docs-subgroup": "Preferences/Notifications" }, "x-whop-surface": "native" }, "/users/me/preferences/notifications/experiences": { "get": { "description": "Lists the authenticated user's per-experience notification levels. Experiences the user never set a level for are omitted — their effective level is `all`.", "operationId": "listUserNotificationExperiencePreferences", "parameters": [ { "description": "The number of preferences to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns preferences after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExperienceNotificationPreference" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "preferences listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Experiences", "tags": [ "Users" ], "x-whop-docs-subgroup": "Preferences/Notifications" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/users/me/preferences/notifications/topics": { "get": { "description": "Lists the authenticated user's topic-scoped notification preferences, plus user-agnostic platform defaults. Each filter matches preferences scoped to its value or not narrowed on that dimension. Per-experience levels are listed separately, by `GET /users/me/preferences/notifications/experiences`.", "operationId": "listUserNotificationTopicPreferences", "parameters": [ { "description": "Only return preferences for this delivery channel (or not narrowed to a channel).", "in": "query", "name": "channel", "required": false, "schema": { "enum": [ "in_app", "mobile" ], "type": "string" } }, { "description": "Only return preferences scoped to this account's member notifications (`biz_` tag).", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this account's team notifications (`biz_` tag).", "in": "query", "name": "team_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this experience (`exp_` tag).", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this notification topic (`topic_` tag).", "in": "query", "name": "topic_id", "required": false, "schema": { "type": "string" } }, { "description": "The number of preferences to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns preferences after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserNotificationPreference" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "preferences listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Topics", "tags": [ "Users" ], "x-whop-docs-subgroup": "Preferences/Notifications" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/users/{id}": { "get": { "description": "Retrieves a user by `user_` tag or username, or the authenticated user with the reserved id `me`. Profiles include linked social accounts — reading your own profile returns every linked account, other profiles only what is public on Whop (the primary Discord and the X account). The self-only fields are populated only when the id is `me`: `email` (email-read scope), `staff` (Whop staff only, staff-read scope), `balance` and `earnings_usd` (balance-read scope), and the opt-in `balance_history`. They are always `null` when addressing a user by tag or username.", "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" } }, { "description": "Also compute your balance history (opt-in; runs a heavier query). Only applies when the id is `me`; ignored for callers without balance-read scope.", "in": "query", "name": "include_balance_history", "required": false, "schema": { "type": "boolean" } }, { "description": "Balance-history window start, ISO 8601 date or datetime. Defaults to 30 days ago. Only used with `include_balance_history`.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history window end, ISO 8601 date or datetime. Defaults to now. Only used with `include_balance_history`.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history point granularity. Defaults to `day`. Only used with `include_balance_history`.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "description": "IANA time zone the balance-history points are bucketed in. Defaults to `UTC`. Only used with `include_balance_history`.", "in": "query", "name": "time_zone", "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": "User ID (prefixed `user_`), username, or `me` for the authenticated user.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a user, addressed by `user_` tag, username, or the reserved id `me` for the authenticated 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": { "banner": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "bio": { "example": "Interior specialist. Leather, upholstery, and odor removal.", "type": "string" }, "name": { "example": "Tanya Cole", "type": "string" }, "profile_picture": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "username": { "example": "tanyacole", "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" ] }, "x-whop-surface": "native" }, "/users/{id}/access/{resource_id}": { "get": { "description": "Checks whether a user has access to an account, product, or experience the caller can reach.", "operationId": "checkUserAccess", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_level": { "enum": [ "no_access", "admin", "customer" ], "example": "customer", "type": "string" }, "has_access": { "example": true, "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": "An account (biz_), product (prod_), or experience (exp_) ID.", "in": "path", "name": "resource_id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/users/{id}/recommend_actions": { "get": { "description": "Lists the recommended actions computed for the user: personal suggestions (e.g. start a business or become an affiliate) pooled with the highest-impact actions across the accounts the user owns. Business actions are tagged with their `account_id`/`account_name`; personal actions leave those `null`. Self-only: `id` must be `me` or the authenticated user's own tag/username.", "operationId": "listUserRecommendedActions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserRecommendedAction" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "recommended actions listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "reading another user's recommended actions" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Recommended Actions", "tags": [ "Users" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "`me`, or the authenticated user's own `user_` tag or username.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/verifications": { "get": { "description": "Returns verifications for an account, including their status and any required actions.", "operationId": "listVerifications", "parameters": [ { "description": "Account or user ID whose verifications you want to list. Use a `biz_` account ID, or the caller's `user_` ID for personal verifications.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Field used to sort returned verifications.", "in": "query", "name": "order", "required": false, "schema": { "default": "updated_at", "enum": [ "updated_at", "created_at" ], "type": "string" } }, { "description": "Sort direction for returned verifications.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted.", "items": { "properties": { "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), or `address` (send `address`).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required identity-read scope" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "List Verifications", "tags": [ "Verifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts a hosted verification session for an account or user, or returns the active session when one already exists. Any fields you include in the request body are used to prefill the session. Send `documents` (with `document_type`) to instead verify the person from identity documents included in this request — no hosted session involved. Send `share_token` to reuse a verification another Sumsub account has already completed for this person, instead of verifying them again. If the account already has an `approved` verification the request is rejected; unlink it first to start a new one.", "operationId": "createVerification", "parameters": [ { "description": "Account or user ID whose identity you want to verify. Use a `biz_` account ID for account verifications, or the caller's `user_` ID for personal verification.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "discriminator": { "propertyName": "kind" }, "oneOf": [ { "description": "Request body for an individual (KYC) verification. Omit `kind` or set it to `individual`. KYC is required to pay out funds and is a prerequisite for Whop Card access. Accepting payments does not require verification until a business reaches $5000 in payments.\n\nAdd `business_name` and `business_structure` if the individual operates under a business entity — this enables payouts to be received by a business bank account. `country` is always the individual's own country, and the supported `business_structure` values vary by it — see [Business structures](/developer/verification/business-structures).", "properties": { "address": { "description": "Every value accepts `null`, so a form seeded from a previous response can round-trip unset fields unchanged.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "Legal business name for a sole proprietor or single-member LLC.", "example": "Shine Time Auto Detailing LLC", "type": "string" }, "business_structure": { "description": "Entity type for sole proprietors, such as `single_member_llc`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "private_corporation", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "business_website": { "description": "Business website URL. Whop store pages are not accepted.", "example": "https://shinetime.example", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "document_type": { "description": "Identity document being sent, when verifying with `documents`. Decides exactly which file slots to send: `ID_CARD` → `id_card_front` + `id_card_back` + `selfie`; `DRIVERS` → `drivers_front` + `drivers_back` + `selfie`; `RESIDENCE_PERMIT` → `residence_permit_front` + `residence_permit_back` + `selfie`; `PASSPORT` → `passport_front` + `selfie`. See [Identity documents](/developer/verification/identity-documents).", "enum": [ "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "PASSPORT" ], "example": "RESIDENCE_PERMIT", "type": "string" }, "documents": { "description": "Identity document files, each value the file's raw bytes base64-encoded (JPEG, PNG, or PDF, up to 5MB per file before encoding). Sending this object verifies the person from the files in this request instead of a hosted session — individual verifications only, and the request must also carry `document_type`, `first_name`, `last_name`, `date_of_birth`, `country`, `phone`, `tax_identification_number`, and an `address` with `line1`, `city`, `state`, and `postal_code`. Send every slot for your `document_type` — a missing or rejected file fails the whole request and nothing is submitted; review starts automatically once every document is accepted. See [Identity documents](/developer/verification/identity-documents) for a full walkthrough.", "properties": { "drivers_back": { "description": "Back of the driver's license, base64-encoded. Required when `document_type` is `DRIVERS`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "drivers_front": { "description": "Front of the driver's license, base64-encoded. Required when `document_type` is `DRIVERS`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "id_card_back": { "description": "Back of the ID card, base64-encoded. Required when `document_type` is `ID_CARD`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "id_card_front": { "description": "Front of the ID card, base64-encoded. Required when `document_type` is `ID_CARD`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "passport_front": { "description": "Photo page of the passport, base64-encoded. Required when `document_type` is `PASSPORT`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "residence_permit_back": { "description": "Back of the residence permit, base64-encoded. Required when `document_type` is `RESIDENCE_PERMIT`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "residence_permit_front": { "description": "Front of the residence permit, base64-encoded. Required when `document_type` is `RESIDENCE_PERMIT`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "selfie": { "description": "Photo of the person's face, base64-encoded. Always required, with every document type. Must be JPEG or PNG.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" } }, "type": "object" }, "first_name": { "example": "Marcus", "type": "string" }, "kind": { "description": "Verification type. Defaults to `individual`.", "enum": [ "individual" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": "string" }, "phone": { "example": "+xxxxxxxxxxx", "type": "string" }, "share_token": { "description": "Sumsub share token for a person a partner has already verified, generated by their Sumsub account for Whop's client ID. Reuses that verification instead of collecting anything: Whop imports the shared identity, rechecks it against its own requirements, and returns `approved` when it satisfies them, or `pending` with a `session_url` covering only what is still missing. Requires a Reusable KYC agreement between the partner's Sumsub account and Whop's. Each token works once, and cannot be combined with `documents` or `document_type`.", "example": "_act-sbx-jwt-eyJhbGciOiJub25l", "type": "string" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" } }, "title": "CreateIndividualVerification", "type": "object" }, { "description": "Request body for a business entity (KYB) verification. Set `kind` to `business`. KYB includes everything KYC provides and additionally unlocks financing options for payments and business Whop Cards.", "properties": { "address": { "description": "Every value accepts `null`, so a form seeded from a previous response can round-trip unset fields unchanged.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing LLC", "type": "string" }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "private_corporation", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "business_website": { "description": "Business website URL. Whop store pages are not accepted.", "example": "https://shinetime.example", "type": "string" }, "country": { "description": "Country of incorporation as a two-letter ISO 3166-1 country code.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Business representative's date of birth, formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "first_name": { "description": "First name of the business representative, used to prefill the verification session.", "example": "Marcus", "type": "string" }, "kind": { "description": "Must be `business` to start a KYB verification.", "enum": [ "business" ], "example": "business", "type": "string" }, "last_name": { "description": "Last name of the business representative, used to prefill the verification session.", "example": "Webb", "type": "string" }, "place_of_incorporation": { "description": "State or region where the business is incorporated.", "example": "TX", "type": "string" }, "share_token": { "description": "Sumsub share token for a person a partner has already verified, generated by their Sumsub account for Whop's client ID. Reuses that verification instead of collecting anything: Whop imports the shared identity, rechecks it against its own requirements, and returns `approved` when it satisfies them, or `pending` with a `session_url` covering only what is still missing. Requires a Reusable KYC agreement between the partner's Sumsub account and Whop's. Each token works once, and cannot be combined with `documents` or `document_type`.", "example": "_act-sbx-jwt-eyJhbGciOiJub25l", "type": "string" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" } }, "title": "CreateBusinessVerification", "type": "object" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted.", "items": { "properties": { "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), or `address` (send `address`).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted.", "items": { "properties": { "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), or `address` (send `address`).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/new", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "pending", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "type": "object" } } }, "description": "verification created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required identity-write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "identity:write" ] } ], "summary": "Create Verification", "tags": [ "Verifications" ] }, "x-whop-surface": "native" }, "/verifications/{id}": { "get": { "description": "Returns verifications for an account, including their status and any required actions.", "operationId": "getVerification", "parameters": [ { "description": "Verification profile ID, prefixed `idpf_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted.", "items": { "properties": { "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), or `address` (send `address`).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "type": "object" } } }, "description": "verification retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no verification with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "identity:read" ] }, { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Retrieve Verification", "tags": [ "Verifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates editable profile details or submits answers for items returned in `requested_information`. Once a verification is `approved` its profile details are locked and can no longer be edited.", "operationId": "updateVerification", "parameters": [ { "description": "Verification profile ID, prefixed `idpf_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "requested_information": [ { "id": "inrqi_textxxxxxx", "value": "https://example.com", "value_type": "raw" }, { "address": { "city": "Austin", "country": "US", "line1": "4180 Burnet Rd", "postal_code": "78756", "state": "TX" }, "id": "inrqi_addrxxxxxx" }, { "file": "upload_xxxxxxxxxxxx", "id": "inrqi_filexxxxxx" } ] }, "oneOf": [ { "description": "Fields that can be updated on an individual (KYC) verification. At least one field is required.", "properties": { "business_name": { "description": "Legal business name for a sole proprietor or single-member LLC.", "example": "Shine Time Auto Detailing", "type": "string" }, "business_structure": { "description": "Entity type for sole proprietors, such as `single_member_llc`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "first_name": { "example": "Marcus", "type": "string" }, "last_name": { "example": "Webb", "type": "string" }, "personal_address": { "description": "Personal address for the individual.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "requested_information": { "description": "Answers to items in `requested_information`. Each entry pairs the item `id` with one answer payload matching its `type`.", "items": { "properties": { "address": { "description": "Answer for `address` items.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "documents": { "description": "Answer for an `id_document` item: the same slot keys Create Verification takes, so the key names both the document and the side. Send every slot for the ID you are uploading — `PASSPORT` is `passport_front`; `ID_CARD`, `DRIVERS` and `RESIDENCE_PERMIT` take a front and a back. Each value is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "properties": { "drivers_back": { "description": "Back of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "drivers_front": { "description": "Front of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_back": { "description": "Back of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_front": { "description": "Front of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "passport_front": { "description": "Photo page of the passport.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_back": { "description": "Back of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_front": { "description": "Front of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "files": { "description": "Answer for a `files` item — one document, as a list of its pages, first page first. Each entry is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "items": { "description": "A direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "id": { "description": "Item ID from `requested_information`.", "example": "inrqi_xxxxxxxxxxxxxx", "type": "string" }, "value": { "description": "Answer for `text`, `date`, `phone`, and `select` items, and the chosen document type for a `file` item that lists `options`.", "example": "Mobile detailing only; no retail storefront.", "type": "string" }, "value_type": { "description": "Whether `value` is raw input or a vault token.", "enum": [ "raw", "vault_token" ], "example": "raw", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" } }, "title": "UpdateIndividualVerification", "type": "object" }, { "description": "Fields that can be updated on a business entity (KYB) verification. At least one field is required.", "properties": { "business_address": { "description": "Business address.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing", "type": "string" }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Business representative's date of birth, formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "first_name": { "description": "First name of the business representative.", "example": "Marcus", "type": "string" }, "last_name": { "description": "Last name of the business representative.", "example": "Webb", "type": "string" }, "requested_information": { "description": "Answers to items in `requested_information`. Each entry pairs the item `id` with one answer payload matching its `type`.", "items": { "properties": { "address": { "description": "Answer for `address` items.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "documents": { "description": "Answer for an `id_document` item: the same slot keys Create Verification takes, so the key names both the document and the side. Send every slot for the ID you are uploading — `PASSPORT` is `passport_front`; `ID_CARD`, `DRIVERS` and `RESIDENCE_PERMIT` take a front and a back. Each value is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "properties": { "drivers_back": { "description": "Back of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "drivers_front": { "description": "Front of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_back": { "description": "Back of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_front": { "description": "Front of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "passport_front": { "description": "Photo page of the passport.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_back": { "description": "Back of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_front": { "description": "Front of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "files": { "description": "Answer for a `files` item — one document, as a list of its pages, first page first. Each entry is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "items": { "description": "A direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "id": { "description": "Item ID from `requested_information`.", "example": "inrqi_xxxxxxxxxxxxxx", "type": "string" }, "value": { "description": "Answer for `text`, `date`, `phone`, and `select` items, and the chosen document type for a `file` item that lists `options`.", "example": "Mobile detailing only; no retail storefront.", "type": "string" }, "value_type": { "description": "Whether `value` is raw input or a vault token.", "enum": [ "raw", "vault_token" ], "example": "raw", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" } }, "title": "UpdateBusinessVerification", "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted.", "items": { "properties": { "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), or `address` (send `address`).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "pending_upload", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "type": "object" } } }, "description": "verification updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body has unsupported fields" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required identity-write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no verification with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "identity:write" ] } ], "summary": "Update Verification", "tags": [ "Verifications" ] }, "x-whop-surface": "native" }, "/webhooks": { "get": { "description": "Returns a paginated list of webhook endpoints configured for an account, ordered by most recently created.", "operationId": "listWebhooks", "parameters": [ { "description": "The unique identifier of the account to list webhooks for.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Only return webhooks attached to this app. Omit to list the account's own webhooks.", "in": "query", "name": "app_id", "required": false, "schema": { "type": "string" } }, { "description": "Also return webhooks attached to the account's apps, not just the account's own. Cannot be combined with `app_id`.", "in": "query", "name": "include_app_webhooks", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return webhooks whose endpoint is currently failing — every delivery since the current failure streak began has been rejected. Clears as soon as a delivery succeeds.", "in": "query", "name": "has_failures", "required": false, "schema": { "type": "boolean" } }, { "description": "The number of webhooks to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns webhooks after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of webhooks to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns webhooks before this position.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "webhooks listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "List Webhooks", "tags": [ "Webhooks" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a webhook endpoint that receives event notifications via HTTP POST.", "operationId": "createWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "The dated API version (Api-Version-Date) to pin this webhook's payloads to. Omit to leave the webhook unpinned, tracking the current payload shape.", "example": "2026-08-25-2", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether to send events for child resources. For example, if the webhook is created for an account, enabling this sends events only from its connected accounts.", "example": true, "type": "boolean" }, "enabled": { "description": "Whether or not the webhook is enabled. Defaults to `true`.", "example": true, "type": "boolean" }, "events": { "description": "The events to send the webhook for, in dot form (for example `payment.succeeded`).", "items": { "enum": [ "account.updated", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "transfer.created", "transfer.completed", "transfer.failed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "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", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "ad_campaign.payment_failed", "chat.message.created", "chat.reaction.created", "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", "membership_went_valid", "membership_went_invalid", "membership_metadata_updated", "resolution_created", "resolution_updated", "resolution_decided", "payment_affiliate_reward_created", "membership_experience_claimed", "app_membership_went_valid", "app_membership_went_invalid", "app_payment_created", "app_payment_succeeded", "app_payment_failed", "app_payment_pending", "app_membership_cancel_at_period_end_changed", "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", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" }, "resource_id": { "description": "The account or app to create the webhook for. Defaults to the current account.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "url": { "description": "The URL to send the webhook to.", "example": "https://example.com/hooks", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "webhook created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "api_version is no longer an input" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no resource with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Create Webhook", "tags": [ "Webhooks" ] }, "x-whop-surface": "native" }, "/webhooks/{id}": { "delete": { "description": "Permanently deletes a webhook endpoint. Returns `true` on success, matching the legacy proxy response.", "operationId": "deleteWebhook", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`: the resource was deleted.", "example": true, "type": "boolean" }, "id": { "description": "The ID of the deleted resource.", "example": "hook_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "webhook deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Delete Webhook", "tags": [ "Webhooks" ] }, "get": { "description": "Retrieves the details of an existing webhook.", "operationId": "retrieveWebhook", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "legacy webhook testable events use dot-form names" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Retrieve Webhook", "tags": [ "Webhooks" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a webhook endpoint's URL, subscribed events, pinned payload version, or enabled state.", "operationId": "updateWebhook", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "The dated API version (Api-Version-Date) to pin this webhook's payloads to. Only valid for `v1` webhooks. Omit to leave the current pin unchanged, or pass `null` to unpin and track the current payload shape.", "example": "2026-08-25-2", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether or not to send events for child resources.", "example": true, "type": "boolean" }, "enabled": { "description": "Whether or not the webhook is enabled.", "example": false, "type": "boolean" }, "events": { "description": "The events to send the webhook for, in dot form (for example `payment.succeeded`).", "items": { "enum": [ "account.updated", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "transfer.created", "transfer.completed", "transfer.failed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "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", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "ad_campaign.payment_failed", "chat.message.created", "chat.reaction.created", "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", "membership_went_valid", "membership_went_invalid", "membership_metadata_updated", "resolution_created", "resolution_updated", "resolution_decided", "payment_affiliate_reward_created", "membership_experience_claimed", "app_membership_went_valid", "app_membership_went_invalid", "app_payment_created", "app_payment_succeeded", "app_payment_failed", "app_payment_pending", "app_membership_cancel_at_period_end_changed", "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", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_membership.cancel_at_period_end_changed" ], "example": "payment.failed", "type": "string" }, "type": "array" }, "url": { "description": "The URL to send the webhook to.", "example": "https://example.com/shine-time/whop-updated", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "webhook updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "api_version is no longer an input" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Update Webhook", "tags": [ "Webhooks" ] }, "x-whop-surface": "native" }, "/webhooks/{id}/deliveries": { "get": { "description": "Returns a paginated list of delivery attempts for a webhook, ordered by most recent first. Includes the request payload, response body, response code, and timing for each attempt.", "operationId": "listWebhookDeliveries", "parameters": [ { "description": "The number of deliveries to return (default 50, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns deliveries after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "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": "deliveries listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "List Deliveries", "tags": [ "Webhooks" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/webhooks/{id}/deliveries/{delivery_id}/replay": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Delivery ID, prefixed `whdel_`, from the List Deliveries endpoint.", "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-sends the exact payload of a past delivery to the webhook's current URL and returns the delivery result. By default the replay keeps the original `webhook-id`, so consumers that deduplicate on it can drop events they already processed. Pass `regenerate_id` to re-send under a freshly generated `webhook-id` instead, so a deduplicating consumer processes the replay as a new message. Only available for enabled webhooks on API version v1; deliveries are retained for 30 days.", "operationId": "replayWebhookDelivery", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "regenerate_id": { "description": "Re-send the delivery under a freshly generated `webhook-id` (in both the envelope and the signed headers) instead of the original one. Defaults to false. Use this when your endpoint deduplicates on `webhook-id` and you want it to process the replay as a new message.", "example": true, "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "example": { "body": "OK", "status": 200, "success": true }, "properties": { "body": { "description": "The body your endpoint returned for the replayed request, as raw text. Empty when the endpoint could not be reached.", "example": "OK", "type": "string" }, "status": { "description": "The HTTP response code your endpoint returned for the replayed request, or 0 when it could not be reached (timeout, DNS, or connection failure).", "example": 200, "type": "integer" }, "success": { "description": "Whether your endpoint acknowledged the replay with a 2xx response.", "example": true, "type": "boolean" } }, "required": [ "status", "body", "success" ], "type": "object" } } }, "description": "delivery replayed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "webhook is not on API version v1" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no delivery with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Replay Delivery", "tags": [ "Webhooks" ] }, "x-whop-surface": "native" }, "/webhooks/{id}/replay": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-sends the webhook's past deliveries within a time window, optionally limited to specific events or to messages whose most recent delivery attempt failed. Fire and forget: nothing about the replay is stored, and each re-send appears as a new entry in the webhook's delivery log. Each matching message is re-sent once, by default with its original `webhook-id`, so consumers that deduplicate are unaffected; pass `regenerate_ids` to re-send under freshly generated ids instead. Only available for enabled webhooks on API version v1; deliveries are retained for 30 days.", "operationId": "replayWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "description": "Only replay these event types, in dot form (for example `payment.succeeded`). Omit to include every event.", "items": { "type": "string" }, "type": "array" }, "failed_only": { "description": "Only replay messages whose most recent delivery attempt in the window failed. Defaults to false. Best-effort: a message whose attempts span processing batches can still be re-sent — replays keep the original `webhook-id` by default, so consumers that deduplicate are unaffected.", "example": true, "type": "boolean" }, "regenerate_ids": { "description": "Re-send each replayed message under a freshly generated `webhook-id` (in both the envelope and the signed headers) instead of its original one. Defaults to false. Use this when your endpoint deduplicates on `webhook-id` and you want it to process the replays as new messages.", "example": true, "type": "boolean" }, "sent_after": { "description": "Start of the delivery window to replay, as an ISO 8601 timestamp. Clamped to the 30-day delivery retention.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "sent_before": { "description": "End of the delivery window to replay, as an ISO 8601 timestamp. Defaults to now.", "type": "string" } }, "required": [ "sent_after" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "example": { "queued": true }, "properties": { "queued": { "description": "Whether the replay was accepted. Watch the webhook's delivery log for the re-sends.", "example": true, "type": "boolean" } }, "required": [ "queued" ], "type": "object" } } }, "description": "replay queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing sent_after" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Replay Deliveries in a Range", "tags": [ "Webhooks" ] }, "x-whop-surface": "native" }, "/webhooks/{id}/test": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Sends a sample payload for the given event to the webhook's URL and returns the delivery result.", "operationId": "testWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "event": { "description": "The event to test the webhook for, in dot form (for example `payment.succeeded`).", "example": "payment.succeeded", "type": "string" } }, "required": [ "event" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "The body of the webhook response.", "example": "OK" }, "status": { "description": "The HTTP response code of this request.", "example": 200, "type": "integer" }, "success": { "description": "Whether or not the webhook test was successful.", "example": true, "type": "boolean" } }, "required": [ "status", "body", "success" ], "type": "object" } } }, "description": "test event sent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing event" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Send Test Event", "tags": [ "Webhooks" ] }, "x-whop-surface": "native" }, "/webhooks/{webhook_id}/deliveries": { "get": { "description": "Returns a paginated list of delivery attempts for a webhook, ordered by most recent first. Includes the request payload, response body, response code, and timing for each attempt.\n\nRequired permissions:\n - `developer:manage_webhook`", "operationId": "deliveriesWebhook", "parameters": [ { "description": "The unique identifier of the webhook to list deliveries for.", "in": "path", "name": "webhook_id", "required": true, "schema": { "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" }, "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" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for WebhookLog.", "properties": { "data": { "description": "A list of nodes.", "items": { "description": "A webhook log entry containing the request and response details", "properties": { "request_body": { "additionalProperties": true, "description": "The request body sent to the webhook endpoint", "type": "object" }, "resource_id": { "description": "The ID of the resource that triggered the webhook", "type": "string" }, "response_body": { "additionalProperties": true, "description": "The response body received from the webhook endpoint", "type": "object" }, "response_code": { "description": "The HTTP response code received from the webhook endpoint", "example": 42, "type": "integer" }, "sent_at": { "description": "The timestamp when the webhook was sent", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "total_time": { "description": "The total time taken to send the webhook request in seconds", "example": 6.9, "type": "number" } }, "required": [ "request_body", "resource_id", "response_body", "response_code", "sent_at", "total_time" ], "type": "object" }, "type": "array" }, "page_info": { "description": "Information to aid in pagination.", "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" } }, "required": [ "end_cursor", "has_next_page" ], "type": "object" } }, "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" }, "429": { "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": "Too many requests" }, "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 deliveries", "tags": [ "Webhooks" ], "x-group-title": "Developer" } } }, "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": "An Account represents a person or business on Whop that can have its own profile, wallet, and account-scoped settings. Use accounts for customers, creators, merchants, sellers, or connected businesses your integration supports.\n\nUse the Accounts API to create accounts, list accounts visible to your credentials, retrieve or update an account, suspend a connected account managed by your platform, and retrieve the account associated with the current API key.\n", "name": "Accounts", "x-whop-summary": "A business on Whop: profile, wallet, capabilities, settings." }, { "description": "A User represents a person on Whop. Users have a public profile and can buy products, join accounts, and access experiences.\n\nUse the Users API to search for users, retrieve or update profiles, and check whether a user has access to an account, product, or experience.\n", "name": "Users", "x-whop-summary": "A person on Whop: profile and connected identities." }, { "description": "A Team Member is a member of an account's team: the link between a user and an account, carrying the role that controls what they can do. Roles are either system roles (like `admin` or `moderator`) or `custom` roles managed from the dashboard.\n\nUse the Team Members API to list an account's team, add a user to the team with a system role, change a member's role, and remove members. Adding a user who has not yet accepted sends an invitation instead.\n", "name": "Team Members", "x-whop-summary": "An account's team members and the roles that scope their access." }, { "description": "A Member is one buyer's relationship with an account — one record per customer regardless of how many memberships they hold. It carries relationship-level state: whether they have joined or left, their access level (`customer`, `admin`, or `no_access`), when they joined, and when they last opened the account's content.\n\nUse the Members API to list an account's members with filtering by access level, status, join date, and name or username search, and to retrieve a single member. Member rows are created and maintained by the membership lifecycle; to grant or revoke access, work with memberships instead.\n", "name": "Members", "x-whop-summary": "One buyer's relationship with an account, across all their purchases." }, { "name": "Webhooks", "x-whop-summary": "Event notifications pushed to your server as things happen." }, { "description": "Stats represent aggregated activity for an account over time. They help you understand revenue, transactions, disputes, members, referrals, and advertising performance across reporting periods like days, weeks, or months.\n\nUse the Stats API to list available metrics and their filterable properties, then retrieve time-series values for a date range.\n", "name": "Stats", "x-whop-summary": "Aggregated financial, audience, and traffic reporting." }, { "description": "A Verification represents a legal identity for a person or business. Accounts and users complete verification when Whop needs to confirm who they are before enabling payouts or compliance-sensitive workflows.\n\nUse the Verifications API to start or resume a hosted verification session, check review status, and submit requested details or documents. If `requested_information` contains items, submit answers with [Update Verification](/api-reference/beta/verifications/update-verification).\n", "name": "Verifications", "x-whop-summary": "Legal identity required before payouts and card issuing." }, { "description": "An Export is an asynchronous CSV of one resource for one account — members, payments, disputes, ads, and the other tables the Whop dashboard can export. Generating a full table takes longer than a request, so an export is created in `pending`, moves through `processing`, and lands on `completed` with a download link. Each resource requires that resource's own export scope.\n\nUse the Exports API to start an export, poll it until `download_url` is set, and list the exports already requested for an account. Finished CSVs are retained for 30 days, after which the file is deleted and the export moves to `expired`.\n", "name": "Exports", "x-whop-summary": "Asynchronous CSV dumps of an account's dashboard data." }, { "description": "A Notification is a message delivered to a user — a new post, a payment, a mention. Every notification comes from an experience the user belongs to or a team they are on, and users control what they receive with notification preferences.\n\nEvery notification belongs to a topic: the category it falls under, such as new sales or account activity. Topics carry a default, so a user only needs a preference row where they diverge from it. `GET /notifications/topics` lists the platform's visible topics, and a topic's `id` is what the notification preference endpoints take as `topic_id` — the catalog is the only place those ids come from, so read it rather than hardcoding. Each topic also carries an `identifier` such as `new-follower`, which is stable across environments and is the value to match on in code.\n\nUse the Notifications API to list the authenticated user's feed, read per-experience unread badges, mark an experience (or everything) as read, send notifications from your app to an experience's users or an account's team, and list the topic catalog.\n", "name": "Notifications", "x-whop-summary": "The user's notification feed: unread badges, mark-read, app sends, and the topic catalog." }, { "description": "A Payment is one charge against a buyer. Create an on-session payment with a `confirmation_token` for the method the buyer selected, or an off-session payment with an existing member's stored payment method.\n\nCollection runs in the background, so the create response is not the outcome. Poll [Retrieve status](/api-reference/beta/payments/retrieve-status) for how far the payment has got and, while it is `requires_action`, what the buyer must do next — follow a redirect, complete 3D Secure, display transfer instructions, or link a bank account. Use the return_url operation to change where they land afterwards, up until they come back.\n", "name": "Payments", "x-whop-summary": "A charge against a buyer, and the step they still owe." }, { "description": "A Confirmation Token is a single-use, short-lived reference to a payment method and billing details collected from a buyer. Its response contains only a display-safe preview and never returns the underlying payment credential.\n\nCreate a confirmation token in a buyer-facing collection flow, then send its `ctok_` ID to the Payments API from your server. Retrieve a token to display its payment method and billing preview or check whether it is still usable.\n", "name": "Confirmation Tokens", "x-whop-summary": "A short-lived reference to payment details collected from a buyer." }, { "description": "A Setup Intent saves a buyer's payment method for later without taking money now. It runs the same collection flow a payment does, so the buyer may still owe a step — 3D Secure on a card, a hosted enrollment, or linking a bank account.\n\nPoll [Retrieve status](/api-reference/beta/setup-intents/retrieve-status) for how far the setup has got and what is outstanding. Once it reaches `succeeded` the method is on file and can be charged.\n", "name": "Setup Intents", "x-whop-summary": "Saving a buyer's payment method without charging it." }, { "description": "A Ledger Activity row is a single financial event on an account's ledger — a payment, payout, refund, transfer, on-chain deposit, swap, or card transaction. Each row is derived from the underlying ledger lines and carries a typed `resource` and `source` so you can present and link the event without extra lookups.\n\nUse Ledger Activity to build a statement or transaction feed for an account or user. Reconcile against your own records with `amount` (signed, in the currency's smallest precision units) and `posted_at`, and use `available_at` to know when inflows became withdrawable.\n", "name": "Ledgers", "x-whop-summary": "The activity feed behind an account or user's balance." }, { "description": "Payouts represent money sent from an account or user balance to an external destination, such as a bank account, wallet, or other saved payout method.\n\nUse the Payouts API to create and track payouts, manage saved payout methods, and show expected arrival details for funds leaving Whop.\n", "name": "Payouts", "x-whop-summary": "Send money from a balance to a bank or wallet." }, { "description": "Cards represent Whop-issued virtual payment cards that spend from an account or user balance. Cards can be assigned to cardholders and configured with spending limits for controlled spending.\n\nUse the Cards API to issue cards, list cards for an account or user, and retrieve active card details such as the card number and CVC.\n", "name": "Cards", "x-whop-summary": "Issue cards that spend from a balance." }, { "description": "Transfers move value between identities on Whop. They are used for account-to-account money movement, user payouts inside Whop, crypto transfers, and claim links depending on the destination type.\n\nUse the Transfers API to create a transfer, list previous transfers, and retrieve a transfer by ID when reconciling money movement between accounts or users.\n", "name": "Transfers", "x-whop-summary": "Move funds between Whop accounts and users." }, { "description": "A Dispute is a chargeback a customer files against a payment through their bank, or an inquiry that may become one. It carries the disputed payment, a deadline to respond, your evidence, and the outcome once the processor rules.\n\nUse the Disputes API to list disputes, edit the evidence packet while a dispute is still contestable, and submit it for review.\n", "name": "Disputes", "x-whop-summary": "Chargebacks filed against an account, with evidence and outcomes." }, { "description": "A Dispute alert is an early warning from a card issuer that a settled payment is being questioned, ahead of any chargeback. `type` separates fraud reports (`early_fraud_warning`), pre-dispute notices (`dispute_alert`), and Visa RDR cases the network already closed by refunding (`rapid_dispute_resolution`).\n\nUse the Dispute alerts API to list alerts for an account, filter them by type or payment, and read `actionable` to see whether refunding can still avoid the chargeback.\n", "name": "Dispute alerts", "x-whop-summary": "Issuer warnings that arrive before a chargeback does." }, { "description": "Deposits describe ways to add funds to an account balance, including hosted deposit pages, bank deposit instructions, and supported crypto wallet addresses.\n\nUse the Deposits API to create deposit instructions for an account.\n", "name": "Deposits", "x-whop-summary": "Add funds to a balance." }, { "description": "Swaps convert value between supported tokens, chains, or wallet destinations for an account. A swap quote describes the expected output, fees, and approval requirements before you create the swap.\n\nUse the Swaps API to quote a conversion, create the swap, list recent swaps, and retrieve status until the transaction completes.\n", "name": "Swaps", "x-whop-summary": "Convert a balance between currencies." }, { "description": "A Resolution Center Case is opened by a buyer when something is wrong with a purchase — an unwanted renewal, an item that never arrived, or a charge they don't recognize. It is the step before a chargeback: the two sides work it out directly, and Whop decides the case if they can't. Each case carries a reason, a status naming which side it is waiting on, a timeline of events, and the actions available to whoever is reading it.\n\nUse the Resolution Center Cases API from either side: as the buyer, open a case, reply, appeal a decision, or withdraw it; as the merchant, accept it (refunding the payment), deny it, or ask the buyer for more information. Both sides read the same case, page its timeline, and summarize the cases they can see.\n", "name": "Resolution Center Cases", "x-whop-summary": "File or respond to a case against a payment, as the buyer or the merchant." }, { "description": "A Product is a digital good or service sold on Whop. Products may contain plans for pricing and/or experiences for content delivery.\n\nUse the Products API to search the public marketplace, list an account's products, retrieve a product, and create, update, or delete products.\n", "name": "Products", "x-whop-summary": "The things you sell. Each owns plans and a store page." }, { "description": "A Plan defines how customers buy a product. It controls pricing, billing cadence, availability, tax behavior, checkout fields, and purchase visibility.\n\nUse the Plans API to create plans for products, list existing plans, retrieve or update plan configuration, calculate tax for checkout, and delete plans that should no longer be offered.\n", "name": "Plans", "x-whop-summary": "Pricing for a product: one-time, recurring, trials, stock." }, { "name": "Promo Codes", "x-whop-summary": "Discounts that creators configure for checkout." }, { "description": "A Membership is a customer's purchase of a plan: the subscription or one-time grant that gives them access to a product. It tracks billing state (`active`, `trialing`, `past_due`, and so on), the current period, pending cancellations, custom metadata, and the software license key when the product includes licensing.\n\nUse the Memberships API to list an account's memberships or the caller's own, retrieve one by ID or license key, invite a recipient to join through a free plan, and manage the lifecycle: cancel immediately or at period end, reverse a scheduled period-end cancellation, pause and resume payment collection, extend with free days, generate a transfer link, and update metadata.\n", "name": "Memberships", "x-whop-summary": "A customer's purchase of a plan, from checkout through cancellation." }, { "description": "A Checkout Configuration is a reusable checkout link owned by an account. In `payment` mode it sells a specific plan; in `setup` mode it collects and saves payment details without charging. Each configuration can also override which payment methods are accepted and how 3D Secure is enforced for that checkout.\n\nUse the Checkout Configurations API to create checkout links for an existing or inline plan, list configurations for an account, retrieve the configuration behind a checkout URL, and delete links that should no longer be used.\n", "name": "Checkout Configurations", "x-whop-summary": "Turn a plan into a shareable, prefilled checkout link." }, { "description": "A Payment Method Domain registers a hostname with a wallet provider so its payment methods can appear at a checkout served from that domain. The domain proves ownership by hosting the provider's association file — for Apple Pay, at `/.well-known/apple-developer-merchantid-domain-association` — and `status` reports whether verification has completed.\n\nUse the Payment Method Domains API to register domains for your account or its connected accounts, retry verification once the association file is hosted, and remove domains that should no longer serve wallet payments. A domain a platform shares with its connected accounts at checkout is listed on the platform's account, not on each connected account.\n", "name": "Payment Method Domains", "x-whop-summary": "Domains verified to show wallet payment methods like Apple Pay at checkout." }, { "description": "A Shipment attaches a carrier tracking number to a payment and follows the package from label creation to delivery, exposing the current delivery status and a customer-facing tracking URL.\n\nUse the Shipments API to list an account's shipments, retrieve one by its id or the payment it fulfills, attach a tracking number to a payment, and update the tracking number on an existing shipment.\n", "name": "Shipments", "x-whop-summary": "Track the delivery of an order by its carrier tracking number." }, { "description": "The Partners API covers your Whop partner activity: the users you referred onto Whop, the businesses you referred and the earnings generated from their processing volume, and the partner leaderboard.\n\nUse it to enroll as a Whop partner, list the users you referred, list your referred businesses and review their earnings, and see the partner leaderboard.\n", "name": "Partners", "x-whop-summary": "The users and businesses you referred to Whop, and what you earn from them." }, { "description": "A Bounty is a paid task posted by an account or user. The reward is held in escrow when the bounty publishes, workers submit proof of completed work, and each accepted submission is paid out until every winner slot fills.\n\nUse the Bounties API to create and publish a bounty, list an account's bounties for reporting or dashboards, list the bounties a user can work or has participated in, and retrieve a single bounty by ID.\n", "name": "Bounties", "x-whop-summary": "Paid tasks with reviewed submissions and escrowed rewards." }, { "description": "A Bounty Submission is one worker's attempt on a bounty. It starts as an in-progress attempt, enters the review queue when proof is submitted, and ends approved (paid from the bounty's escrowed pool) or denied.\n\nUse the Bounty Submissions API to submit proof of completed work to a bounty, list the submissions you authored, and review the submissions on your bounties — across every bounty or narrowed to one.\n", "name": "Bounty Submissions", "x-whop-summary": "Work submitted to a bounty, from attempt to payout." }, { "description": "A Person is an identity-linked profile of a visitor or customer of an account, assembled from every [event](/api-reference/beta/events/event) the person generated — pixel page views, ad clicks, leads, identifies, and payments. Each profile carries the person's known identities (names, emails, phones, user IDs), purchase history and LTV, geo/device profile, traffic sources, and the first and last marketing touches that reached them.\n\nUse the People API to list and segment the people of an account — filter by activity, purchases, traffic source, location, or marketing touch, and sort by value — or retrieve one person by person ID, user ID, email address, or phone number.\n", "name": "People", "x-whop-summary": "Visitors and customers of an account, with identity, purchase, and traffic profiles." }, { "description": "An Event records conversion or engagement activity for an account, such as page views, purchases, or leads. Each event ties the action to the [person](/api-reference/beta/people/person) who took it, so activity can be attributed to the ads and links that drove it.\n\nUse the Events API to send new tracking events, list recent identity-linked events for an account, and inspect the events recorded for a person. The resource also exposes an anonymized read mode — the pulse feed — a platform-wide snapshot of recent purchases that carries nothing identifying. The pulse feed is public; other Events endpoints require authentication and are scoped to an account.\n\nEvents are only as good as the pixel sending them, so [Validate Pixel](/api-reference/beta/events/validate-pixel) answers whether an account's pixel is working: it reads the events the pixel has sent, and when you pass a `url` whose page hasn't sent any lately, it fetches that page and looks for the pixel in its source. Use it before launching an ad to confirm its destination is tracked, or in a setup flow to tell a merchant whether their install is live.\n", "name": "Events", "x-whop-summary": "Conversion and engagement events tracked for attribution." }, { "description": "A Report is a pre-built analytics payload for an account, assembled from pixel events. Reports cover traffic today — page views and visitors over time, top pages, sources, devices, countries, and weekday activity.\n\nUse the Reports API to list the available reports and their accepted parameters, then retrieve one report for a date range.\n", "name": "Reports", "x-whop-summary": "Pre-built traffic analytics tables and series." }, { "description": "A Recommended Action Chain is a short, ordered sequence of dashboard actions — create a product, price it, publish it — suggested for an account based on what it already has. Seeded chains come from hand-written presets; generated chains, produced per account, share the same shape.\n\nUse the Recommended Actions API to list the chains recommended for an account and to record that a chain was run. Running a chain executes nothing server-side — the client follows each step's CTA itself; the run endpoint records the `recommended_action_chain.executed` analytics event.\n", "name": "Recommended Actions", "x-whop-summary": "Suggested next-step action chains for an account." }, { "description": "An Ad is the individual creative unit delivered by an [ad group](/api-reference/beta/ad-groups/ad-group). It holds the copy, creative assets, and destination URL for one ad.\n\nUse the Ads API to list ads for an account, create ads inside ad groups, retrieve or update creative details, delete ads that should stop running, and pause or resume delivery.\n", "name": "Ads", "x-whop-summary": "The creative: copy, assets, and destination URL." }, { "description": "An Ad Campaign is the top-level container for paid ads on an ad network. It sets the platform, objective, and budget strategy shared by its [ad groups](/api-reference/beta/ad-groups/ad-group) and ads.\n\nUse the Ad Campaigns API to create campaigns, list campaigns for an account, retrieve or update campaign settings, and pause or resume campaign delivery.\n", "name": "Ad Campaigns", "x-whop-summary": "Platform, objective, and budget for a set of ads." }, { "description": "An Ad Group sits inside an [ad campaign](/api-reference/beta/ad-campaigns/ad-campaign) and controls delivery for [ads](/api-reference/beta/ads/ad). It sets the audience, placements, schedule, budget, and optimization goal for its ads.\n\nUse the Ad Groups API to create ad groups in campaigns, list or retrieve targeting and delivery settings, update budgets or targeting, delete groups that should stop running, and pause or resume delivery. It can also search the ad platform's targeting taxonomy for options to target and estimate how many people a draft targeting spec can reach.\n", "name": "Ad Groups", "x-whop-summary": "Audience, placements, and schedule within a campaign." }, { "description": "An Audience represents a customer list uploaded to Whop for ad targeting. Audiences belong to an account and sync to supported ad platforms as custom audiences.\n\nUse the Audiences API to create audiences from CSV uploads, monitor processing status, and list or delete audiences for an account. Created audiences are usable for targeting after processing reaches `ready` or `partial`.\n", "name": "Audiences", "x-whop-summary": "Reusable targeting lists for ad groups." }, { "description": "A File is an uploaded document or media object, identified by a `file_` ID. Creating a file returns a presigned destination; upload the bytes there and the file becomes `ready`.\n\nUse the Files API to create a file, upload its content directly to storage (in one PUT, or in parts for large files), and retrieve it while polling for readiness. A ready file's ID can be attached wherever Whop accepts files.\n", "name": "Files", "x-whop-summary": "Upload files and attach them wherever Whop accepts documents." }, { "description": "A Media Asset is an AI-generated image or video created from a prompt and billed from an account balance. When generation finishes, the asset includes a file that can be attached anywhere Whop accepts files.\n\nUse the Media API to start a generation job and retrieve the asset while it processes or after it is ready.\n", "name": "Media", "x-whop-summary": "AI-generated assets, billed from a balance, attachable wherever files are accepted." }, { "description": "A Social Account represents an external profile connected to a Whop account or user, such as a Facebook page or Instagram account. Connecting a social account lets Whop run [ads](/api-reference/beta/ads/ad) under that profile's identity and promote its existing posts.\n\nUse the Social Accounts API to list connected accounts, create a Whop-managed Facebook page, start an OAuth connection, disconnect a social account, and list a connected profile's posts or a Facebook page's lead forms.\n", "name": "Social Accounts", "x-whop-summary": "Connected Facebook and Instagram accounts that run ads." }, { "description": "An App is software you build on Whop. It can be a hosted web app served at `.whop.site` or an API integration installed as an experience, and it belongs to the account that owns its credentials, settings, builds, and runtime logs.\n\nUse the Apps API to manage app configuration, deploy an app's working copy and follow the run on the app's `deployment` field, and, for hosted apps, read server runtime logs for console output, uncaught exceptions, and failed requests. Logs are retained for 7 days and can be filtered by build, level, time window, and message text.\n\nApps are also reusable blueprints. List official blueprints with `app_type=website&verified=true&order=template_usage`, or community blueprints with `app_type=website&verified=false&recommended=true&order=template_usage`. Pass the returned App `id` as `blueprint_id` when creating an Account.\n", "name": "Apps", "x-whop-summary": "Apps you build on Whop: metadata, hosted builds, runtime logs." }, { "description": "An App Build is a versioned artifact uploaded for an app — a hosted web archive, or an iOS/Android bundle. Builds start as drafts, go through review, and one approved build per platform is served to users as the production build.\n\nUse the App Builds API to upload a build for an app, list an app's builds with platform and status filters, retrieve a build, and promote a draft or approved build to production.\n", "name": "App Builds", "x-whop-summary": "Versioned build artifacts deployed to an app's platforms." }, { "description": "An API Key is a programmatic credential owned by an account or app. Each key carries its own permissions policy — explicit permission statements or an inherited system role — and can be restricted with an expiration date and an IP allowlist.\n\nUse the API Keys API to list an account or app's keys, create a key (the full secret is returned once, on creation), inspect a key's effective grants, update its name or restrictions, rotate its secret, and revoke it. These endpoints require a user session — they cannot be called with an API key.\n", "name": "API Keys", "x-whop-summary": "Programmatic credentials for an account or app." }, { "description": "An Api Log is a record of a single request made to Whop's API using one of your account's API keys — the programmatic counterpart to the dashboard audit log, which only records actions taken by signed-in team members. Reads and failed requests are logged too.\n\nUse the Api Logs API to see what your integrations are doing on Whop: the operation, HTTP method and status, outcome, and timing of each request, newest first.\n", "name": "Api Logs", "x-whop-summary": "Requests made to Whop's API with your account's API keys." }, { "description": "A Permission is one action, such as `stats:read`, paired with whether your credential is granted it on a given resource. It answers for whatever you authenticated with, so you can decide what to show or attempt instead of discovering a `403`.\n\nUse the Permissions API to check an account, product, experience, or app, narrowing to the actions you care about. It reports only your own access — to manage who else can reach an account, use the Team Members API.\n", "name": "Permissions", "x-whop-summary": "What your credential is allowed to do on a resource." }, { "description": "An Experiment is a controlled test that assigns users to treatment arms to measure the causal impact of a change; users outside every arm form the implicit control group. A Feature Flag is a simpler form that gates access without collecting metric results — both share the same evaluation API.\n\n**Evaluating flags** — call `GET /experiments/exposures` to check which arm the caller is assigned to. Pass a `flag_key` to evaluate one flag, or omit it to receive the full set at once. Signed-in callers are bucketed by their user identity; anonymous callers supply a stable `anonymous_id` and are served feature flags only, since an anonymous experiment assignment would change at sign-in. Assignments are permanent — ramping a weight up or adding an arm only ever moves control users into a treatment, never between arms or back. Pass `account_id` to activate account-level targeting rules.\n\n**Targeting** — experiments carry flag-level targeting rules that gate who is in the experiment at all: match on user IDs, account IDs, or custom properties, using equality, range, or inclusion operators. Conditions within a rule are AND-ed; rules are OR-ed, and `exclude` rules always win.\n\n**Results** — `GET /experiments/{id}/results` returns per-arm exposures and metric lifts with p-values, significance, and the Bayesian probability of beating the control. Metrics must be pre-registered via the catalog before they can be attached to an experiment.\n\nUse the Experiments API to evaluate flags in application code, and (with Whop internal access) to create experiments, drive their lifecycle (`activate`, `pause`, `end`), update targeting, and read statistical results.\n", "name": "Experiments", "x-whop-summary": "Feature flags and A/B experiments for gradual rollout and statistical measurement." } ], "webhooks": { "account.updated": { "post": { "description": "Sent when an account is updated\n\nRequired permissions:\n - `webhook_receive: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "active", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "active", "standard_payout": "inactive", "transfer": "inactive" }, "cards": null, "collect_vat_id": false, "company_formation": { "status": "draft" }, "country": "us", "created_at": "2026-01-01T12:00:00.000Z", "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "email": "marcus@shinetime.example", "eula": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_group": null, "industry_type": null, "invoice_prefix": "SHINE", "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "other_business_description": null, "other_industry_description": null, "owner": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "parent_account": null, "payment_controls": { "dispute_alert_auto_refund": { "locked": false, "threshold_usd": 500 }, "dispute_alert_fee_usd": 29, "enforce_3ds": false, "financing_disabled": false, "high_risk_processing_fee_percentage": 0, "pending_auto_topup_fee_percentage": 2.0, "pending_balance_delay_days": 0, "reserve": { "hold_period_days": 90, "percentage": null }, "resolution_center_auto_refund": { "card_threshold_usd": null, "financing_threshold_usd": null, "locked": false, "paypal_threshold_usd": null }, "restricted_payment_methods": [], "undated_pending_reason": null, "withdrawal_schedule": { "day": null, "frequency": "manual", "next_payout_date": null } }, "privacy_policy": null, "product_tax_code": null, "recommended_actions": null, "require_2fa": false, "required_actions": [ { "action": "verify_identity", "blocked_capabilities": [], "cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/", "cta_label": "Verify now", "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "icon_url": null, "status": "required", "title": "Ceramic Coating Package" } ], "return_policy": null, "route": "biz_xxxxxxxxxxxxxx", "send_customer_emails": true, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_3", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "stablecoin_rails": false, "status": "active", "status_reason": null, "store_page_config": { "accent_color": "blue", "layout": "featured", "profile_variant": null, "whop_affiliate_link": false }, "target_audience": "Owners of new and enthusiast vehicles in Austin, TX", "tax_collection_enabled_states": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "tax_identifiers": [], "tax_remitted_by": "whop", "tax_type": null, "terms_of_service": null, "three_ds_level": null, "title": "Shine Time Auto Detailing", "total_earned_usd": 0.0, "total_usd": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_usd": 0.0, "wallet": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "previous_attributes": { "title": "Webb's Mobile Detailing" }, "timestamp": "2025-01-01T00:00:00.000Z", "type": "account.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Account" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "example": { "title": "Webb's Mobile Detailing" }, "type": "object" }, "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": "account.updated", "description": "The webhook event type", "example": "account.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Account Updated", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "ad_campaign.payment_failed": { "post": { "description": "Sent when an ad campaign's payment fails and its ads stop delivering\n\nRequired permissions:\n - `webhook_receive:ad_campaigns`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "added_to_cart_value": 0.0, "added_to_carts": 0, "bid_type": null, "budget_amount": 50.0, "budget_optimization": null, "budget_type": "daily", "click_through_rate": 0.0, "clicks": 0, "completed_registration_value": 0.0, "completed_registrations": 0, "contact_value": 0.0, "contacts": 0, "cost_per_added_to_cart": null, "cost_per_click": 0.0, "cost_per_completed_registration": null, "cost_per_contact": null, "cost_per_lead": null, "cost_per_mille": 0.0, "cost_per_purchase": null, "cost_per_result": null, "cost_per_schedule": null, "cost_per_submitted_application": null, "cost_per_unique_click": null, "cost_per_viewed_content": null, "created_at": "2026-01-01T12:00:00.000Z", "custom_conversions": 0, "custom_event_counts": {}, "custom_event_values": {}, "delivery_status": "payment_failed", "frequency": null, "id": "adcamp_xxxxxxxxxxxxxx", "impressions": 0, "issues": [], "lead_value": 0.0, "leads": 0, "link_clicks": 0, "objective": null, "optimization_goal": null, "platform": "meta", "purchase_value": 0.0, "purchases": 0, "reach": 0, "result_event": null, "result_event_name": null, "results": null, "return_on_ad_spend": 0.0, "schedule_value": 0.0, "schedules": 0, "special_ad_categories": [], "spend": 0.0, "spend_currency": null, "status": "payment_failed", "submitted_application_value": 0.0, "submitted_applications": 0, "title": "Ceramic Coating Package", "unique_click_through_rate": null, "unique_clicks": 0, "updated_at": "2026-01-01T12:00:00.000Z", "viewed_content_value": 0.0, "viewed_contents": 0 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "ad_campaign.payment_failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/AdCampaign" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "ad_campaign.payment_failed", "description": "The webhook event type", "example": "ad_campaign.payment_failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Ad Campaign Payment failed", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "card.canceled": { "post": { "description": "Sent when a card is canceled\n\nRequired permissions:\n - `webhook_receive:cards`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.canceled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card.canceled", "description": "The webhook event type", "example": "card.canceled", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Canceled", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card.created": { "post": { "description": "Sent when a card is created\n\nRequired permissions:\n - `webhook_receive:cards`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card.created", "description": "The webhook event type", "example": "card.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Created", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card.frozen": { "post": { "description": "Sent when a card is frozen\n\nRequired permissions:\n - `webhook_receive:cards`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.frozen" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card.frozen", "description": "The webhook event type", "example": "card.frozen", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Frozen", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card.updated": { "post": { "description": "Sent when a card is updated\n\nRequired permissions:\n - `webhook_receive:cards`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card.updated", "description": "The webhook event type", "example": "card.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Updated", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.approved": { "post": { "description": "Sent when a card application is approved\n\nRequired permissions:\n - `webhook_receive:card_applications`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.approved" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_application.approved", "description": "The webhook event type", "example": "card_application.approved", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Approved", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.created": { "post": { "description": "Sent when a card application is created\n\nRequired permissions:\n - `webhook_receive:card_applications`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_application.created", "description": "The webhook event type", "example": "card_application.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Created", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.denied": { "post": { "description": "Sent when a card application is denied\n\nRequired permissions:\n - `webhook_receive:card_applications`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.denied" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_application.denied", "description": "The webhook event type", "example": "card_application.denied", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Denied", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.updated": { "post": { "description": "Sent when a card application is updated\n\nRequired permissions:\n - `webhook_receive:card_applications`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_application.updated", "description": "The webhook event type", "example": "card_application.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Updated", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_transaction.completed": { "post": { "description": "Sent when a card transaction is completed\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.25, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": "2026-01-02T12:00:00.000Z", "status": "completed", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_transaction.completed", "description": "The webhook event type", "example": "card_transaction.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CardTransaction Completed", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_transaction.created": { "post": { "description": "Sent when a card transaction is created\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": null, "status": "pending", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_transaction.created", "description": "The webhook event type", "example": "card_transaction.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CardTransaction Created", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_transaction.declined": { "post": { "description": "Sent when a card transaction is declined\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": "Insufficient funds", "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": null, "status": "declined", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.declined" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_transaction.declined", "description": "The webhook event type", "example": "card_transaction.declined", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CardTransaction Declined", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_transaction.reversed": { "post": { "description": "Sent when a card transaction is reversed\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": "2026-01-02T12:00:00.000Z", "status": "reversed", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.reversed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_transaction.reversed", "description": "The webhook event type", "example": "card_transaction.reversed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CardTransaction Reversed", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_transaction.updated": { "post": { "description": "Sent when a card transaction is updated\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.25, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": "2026-01-02T12:00:00.000Z", "status": "completed", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "card_transaction.updated", "description": "The webhook event type", "example": "card_transaction.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CardTransaction Updated", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "chat.message.created": { "post": { "description": "Sent when a chat event is created\n\nRequired permissions:\n - `webhook_receive:chat`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "audience": { "type": "channel", "user_ids": [ "user_xxxxxxxxxxxxxx", "user_xxxxxxxxxxxxxx" ] }, "channel": { "experience_id": "exp_xxxxxxxxxxxxxx", "id": "feed_xxxxxxxxxxxxxx", "type": "chat" }, "message": { "content": "Hey, are you available for a **quick call**?", "created_at": "2023-12-01T05:00:00.401Z", "id": "some_string", "is_edited": true, "is_pinned": true, "mentions": [ "some_string", "some_string" ], "mentions_everyone": true, "message_type": "regular", "poll": { "options": [ { "id": "some_string", "text": "some_string" }, { "id": "some_string", "text": "some_string" } ] }, "poll_votes": [ { "count": 42, "option_id": "some_string" }, { "count": 42, "option_id": "some_string" } ], "reaction_counts": [ { "count": 42, "emoji": "some_string" }, { "count": 42, "emoji": "some_string" } ], "replying_to_message_id": "some_string", "updated_at": "2023-12-01T05:00:00.401Z", "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" }, "view_count": 42 }, "reason": "channel_message" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "chat.message.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "audience": { "properties": { "type": { "enum": [ "channel", "users" ], "example": "channel", "type": "string" }, "user_ids": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "type" ], "type": "object" }, "channel": { "properties": { "experience_id": { "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "feed_xxxxxxxxxxxxxx", "type": "string" }, "type": { "enum": [ "chat", "direct_message", "support" ], "example": "chat", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "message": { "$ref": "#/components/schemas/Message" }, "reason": { "example": "channel_message", "type": "string" } }, "required": [ "reason", "audience", "channel", "message" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "chat.message.created", "description": "The webhook event type", "example": "chat.message.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Chat Message Created", "tags": [ "Messages" ] } }, "chat.reaction.created": { "post": { "description": "Sent when a chat event is created\n\nRequired permissions:\n - `webhook_receive:chat`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "audience": { "type": "channel", "user_ids": [ "user_xxxxxxxxxxxxxx", "user_xxxxxxxxxxxxxx" ] }, "channel": { "experience_id": "exp_xxxxxxxxxxxxxx", "id": "feed_xxxxxxxxxxxxxx", "type": "chat" }, "message": { "content": "Hey, are you available for a **quick call**?", "created_at": "2023-12-01T05:00:00.401Z", "id": "some_string", "is_edited": true, "is_pinned": true, "mentions": [ "some_string", "some_string" ], "mentions_everyone": true, "message_type": "regular", "poll": { "options": [ { "id": "some_string", "text": "some_string" }, { "id": "some_string", "text": "some_string" } ] }, "poll_votes": [ { "count": 42, "option_id": "some_string" }, { "count": 42, "option_id": "some_string" } ], "reaction_counts": [ { "count": 42, "emoji": "some_string" }, { "count": 42, "emoji": "some_string" } ], "replying_to_message_id": "some_string", "updated_at": "2023-12-01T05:00:00.401Z", "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" }, "view_count": 42 }, "reaction": { "emoji": ":heart:", "id": "reac_xxxxxxxxxxxxxxxxxxxxxx", "resource_id": "some_string", "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" } }, "reason": "message_reaction" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "chat.reaction.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "audience": { "properties": { "type": { "enum": [ "channel", "users" ], "example": "channel", "type": "string" }, "user_ids": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "type" ], "type": "object" }, "channel": { "properties": { "experience_id": { "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "feed_xxxxxxxxxxxxxx", "type": "string" }, "type": { "enum": [ "chat", "direct_message", "support" ], "example": "chat", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "message": { "$ref": "#/components/schemas/Message" }, "reaction": { "$ref": "#/components/schemas/Reaction" }, "reason": { "example": "message_reaction", "type": "string" } }, "required": [ "reason", "audience", "channel", "message", "reaction" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "chat.reaction.created", "description": "The webhook event type", "example": "chat.reaction.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Chat Reaction Created", "tags": [ "Reactions" ] } }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "completed": true, "course": { "experience": { "id": "exp_xxxxxxxxxxxxxx" }, "id": "cors_xxxxxxxxxxxxx", "title": "Introduction to Technical Analysis" }, "created_at": "2023-12-01T05:00:00.401Z", "id": "crsli_xxxxxxxxxxxx", "lesson": { "chapter": { "id": "chap_xxxxxxxxxxxxx" }, "id": "lesn_xxxxxxxxxxxxx", "title": "Understanding Candlestick Patterns" }, "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "course_lesson_interaction.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CourseLessonInteraction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] } }, "deposit.succeeded": { "post": { "description": "Sent when a deposit is succeeded\n\nRequired permissions:\n - `webhook_receive:deposits`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": "750000000", "available_at": null, "currency": { "code": "usdc", "precision": "1000000" }, "id": "line_5", "line_type": "onchain_deposit", "object": "ledger_activity", "posted_at": "2026-01-02T12:00:00.000Z", "resource": null, "source": { "chain": "plasma", "id": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "object": "onchain_transaction", "sender_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "tx_hash": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "deposit.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerActivity" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "deposit.succeeded", "description": "The webhook event type", "example": "deposit.succeeded", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Deposit Succeeded", "tags": [ "Deposits" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 150.0, "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy_attachment": null, "cancellation_policy_disclosure": null, "customer_communication_attachment": null, "customer_email_address": null, "customer_name": null, "documents": [], "notes": null, "product_description": null, "refund_policy_attachment": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": null, "uncategorized_attachment": null }, "evidence_due_at": "2026-01-01T12:00:00.000Z", "evidence_editable": true, "evidence_locked_reason": null, "evidence_submitted_at": null, "generated_response_attachment": null, "id": "dspt_xxxxxxxxxxxxxx", "inquiry": false, "issuer_comments": [], "payment": { "amount": 0.0, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "pay_xxxxxxxxxxxxxx", "payment_instrument": null, "payment_method_type": null, "payment_processor": "stripe" }, "plan_id": null, "product_id": null, "rapid_dispute_resolution": false, "reason": "fraudulent", "reason_code": null, "status": "needs_response", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "dispute.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Dispute" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 150.0, "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy_attachment": null, "cancellation_policy_disclosure": null, "customer_communication_attachment": null, "customer_email_address": "marcus@shinetime.example", "customer_name": "Dana Whitfield", "documents": [], "notes": null, "product_description": "Two-day ceramic coating service, completed as scheduled on the booked date.", "refund_policy_attachment": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": "2026-01-01", "uncategorized_attachment": null }, "evidence_due_at": "2026-01-01T12:00:00.000Z", "evidence_editable": false, "evidence_locked_reason": "submitted", "evidence_submitted_at": "2026-01-01T12:00:00.000Z", "generated_response_attachment": null, "id": "dspt_xxxxxxxxxxxxxx", "inquiry": false, "issuer_comments": [], "payment": { "amount": 0.0, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "pay_xxxxxxxxxxxxxx", "payment_instrument": null, "payment_method_type": null, "payment_processor": "stripe" }, "plan_id": null, "product_id": null, "rapid_dispute_resolution": false, "reason": "fraudulent", "reason_code": null, "status": "under_review", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "dispute.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Dispute" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account_id": null, "actionable": false, "amount": 25.0, "card_brand": "visa", "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "fee_charged": false, "id": "dspa_xxxxxxxxxxxxxx", "issuer": null, "not_actionable_reason": "payment_unmatched", "payment_id": null, "product_id": null, "reported_at": "2026-01-01T12:00:00.000Z", "transaction_at": "2026-01-01T12:00:00.000Z", "type": "dispute_alert", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "dispute_alert.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/DisputeAlert" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Dispute Alert Created", "tags": [ "Dispute alerts" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "approved", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.approved" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "pending", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "pending", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "denied", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.denied" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] } }, "export.completed": { "post": { "description": "Sent when an export is completed\n\nRequired permissions:\n - `webhook_receive:exports`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "created_at": "2026-01-01T12:00:00.000Z", "download_url": "https://s3.amazonaws.com/uploads/exports/members-export.csv", "expires_at": "2026-01-01T12:00:00.000Z", "id": "exprt_xxxxxxxxxxxxxx", "progress_percent": null, "resource": "members", "status": "completed", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "export.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Export" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "export.completed", "description": "The webhook event type", "example": "export.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Export Completed", "tags": [ "Exports" ] }, "x-whop-surface": "native" }, "export.failed": { "post": { "description": "Sent when an export is failed\n\nRequired permissions:\n - `webhook_receive:exports`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "created_at": "2026-01-01T12:00:00.000Z", "download_url": null, "expires_at": "2026-01-01T12:00:00.000Z", "id": "exprt_xxxxxxxxxxxxxx", "progress_percent": null, "resource": "members", "status": "failed", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "export.failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Export" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "export.failed", "description": "The webhook event type", "example": "export.failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Export Failed", "tags": [ "Exports" ] }, "x-whop-surface": "native" }, "identity_profile.updated": { "post": { "description": "Sent whenever an identity profile changes state — a verification is approved, needs action, or is rejected, or a Whop review opens or clears. Every other identity_profile event is also delivered as an identity_profile.updated, so you can subscribe to this single event and re-fetch the verification to read its current status.\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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "id": "idpf_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "identity_profile.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "id": { "description": "The identity profile id (`idpf_`). Re-fetch `GET /verifications` for its current state.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "IdentityProfile Updated", "tags": [ "Verifications" ] }, "x-whop-surface": "native" }, "invoice.created": { "post": { "description": "Sent when a invoice is created\n\nRequired permissions:\n - `invoice:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `payment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx" }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "open", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `member:email:read`\n - `member:basic:read`\n - `payment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx" }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "uncollectible", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.marked_uncollectible" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `member:email:read`\n - `member:basic:read`\n - `payment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx" }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "paid", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.paid" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `member:email:read`\n - `member:basic:read`\n - `payment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx" }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "past_due", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.past_due" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `member:email:read`\n - `member:basic:read`\n - `payment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx" }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "void", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.voided" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Invoice" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] } }, "ledger_account.funds_available": { "post": { "description": "Sent when a ledger account is funds available\n\nRequired permissions:\n - `company:balance:read`\n - `payout:account:read`\n - `webhook_receive:ledger_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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "balances": [ { "balance": 1837.5, "currency": "usd", "pending_balance": 245.0, "reserve_balance": 0.0 } ], "id": "ldgr_xxxxxxxxxxxxxx", "ledger_type": "primary", "owner": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "payments_approval_status": null, "payout_account_details": null, "settlement_time_at": "2026-01-01T12:00:00.000Z", "transfer_fee": 3.0, "treasury_balance": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "ledger_account.funds_available" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerAccount" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "ledger_account.funds_available", "description": "The webhook event type", "example": "ledger_account.funds_available", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "LedgerAccount Funds available", "tags": [ "Ledger accounts" ] } }, "member.created": { "post": { "description": "Sent when a member is created\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `member:phone:read`\n - `webhook_receive:members`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "access_level": "customer", "account_id": "biz_xxxxxxxxxxxxxx", "created_at": "2026-01-01T12:00:00.000Z", "id": "mber_xxxxxxxxxxxxxx", "joined_at": "2026-01-01T12:00:00.000Z", "last_accessed_at": "2026-01-01T12:00:00.000Z", "phone_number": null, "status": "joined", "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "member.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Member" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "member.created", "description": "The webhook event type", "example": "member.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Member Created", "tags": [ "Members" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": false, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "active", "user_id": "user_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.activated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": true, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "active", "user_id": "user_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.cancel_at_period_end_changed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": false, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "canceled", "user_id": "user_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.deactivated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "membership.trial_ending_soon": { "post": { "description": "Sent when a membership is trial ending soon\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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": false, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "trialing", "user_id": "user_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.trial_ending_soon" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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.trial_ending_soon", "description": "The webhook event type", "example": "membership.trial_ending_soon", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Trial ending soon", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "payment.authorized": { "post": { "description": "Sent when a payment is authorized\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 - `shipment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount_after_fees": 50.0, "application_fee": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "card_brand": "visa", "card_exp_month": null, "card_exp_year": null, "card_last4": "4242", "checkout_configuration_id": null, "company": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "disputes": [], "failure_message": null, "fees": [], "financing_installments_count": null, "financing_transactions": [], "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt": null, "member": { "id": "mber_xxxxxxxxxxxxxx", "phone": null }, "membership": { "id": "mem_xxxxxxxxxxxxxx", "phone_number": null, "status": "drafted" }, "metadata": {}, "needs_tracking": false, "next_payment_attempt": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method": null, "payment_method_type": "card", "payments_failed": 0, "plan": { "id": "plan_xxxxxxxxxxxxxx", "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {}, "route": "ceramic-coating-package", "title": "Ceramic Coating Package" }, "promo_code": null, "refundable": false, "refunded_amount": 0.0, "refunded_at": null, "refunds": [], "resolutions": [], "retryable": false, "risk_score": null, "risk_signals": null, "settlement_amount": 50.0, "settlement_currency": "usd", "settlement_exchange_rate": null, "settlement_time_at": null, "shipment": null, "shipping_address": null, "status": "authorized", "substatus": "requires_capture", "subtotal": 50.0, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "three_ds_verified": false, "total": 50.0, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": 50.0, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "verification_checks": null, "voidable": true }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.authorized" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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.authorized", "description": "The webhook event type", "example": "payment.authorized", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Authorized", "tags": [ "Payments" ] } }, "payment.canceled": { "post": { "description": "Sent when a payment is canceled\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 - `shipment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount_after_fees": 50.0, "application_fee": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "card_brand": "visa", "card_exp_month": null, "card_exp_year": null, "card_last4": "4242", "checkout_configuration_id": null, "company": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "disputes": [], "failure_message": null, "fees": [], "financing_installments_count": null, "financing_transactions": [], "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt": null, "member": { "id": "mber_xxxxxxxxxxxxxx", "phone": null }, "membership": { "id": "mem_xxxxxxxxxxxxxx", "phone_number": null, "status": "drafted" }, "metadata": {}, "needs_tracking": false, "next_payment_attempt": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method": null, "payment_method_type": "card", "payments_failed": 0, "plan": { "id": "plan_xxxxxxxxxxxxxx", "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {}, "route": "ceramic-coating-package", "title": "Ceramic Coating Package" }, "promo_code": null, "refundable": false, "refunded_amount": 0.0, "refunded_at": null, "refunds": [], "resolutions": [], "retryable": false, "risk_score": null, "risk_signals": null, "settlement_amount": 50.0, "settlement_currency": "usd", "settlement_exchange_rate": null, "settlement_time_at": null, "shipment": null, "shipping_address": null, "status": "void", "substatus": "canceled", "subtotal": 50.0, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "three_ds_verified": false, "total": 50.0, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": 50.0, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.canceled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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.canceled", "description": "The webhook event type", "example": "payment.canceled", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Canceled", "tags": [ "Payments" ] } }, "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 - `shipment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount_after_fees": 50.0, "application_fee": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "card_brand": "visa", "card_exp_month": null, "card_exp_year": null, "card_last4": "4242", "checkout_configuration_id": null, "company": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "disputes": [], "failure_message": null, "fees": [], "financing_installments_count": null, "financing_transactions": [], "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt": null, "member": { "id": "mber_xxxxxxxxxxxxxx", "phone": null }, "membership": { "id": "mem_xxxxxxxxxxxxxx", "phone_number": null, "status": "active" }, "metadata": {}, "needs_tracking": false, "next_payment_attempt": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method": null, "payment_method_type": "card", "payments_failed": 0, "plan": { "id": "plan_xxxxxxxxxxxxxx", "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {}, "route": "ceramic-coating-package", "title": "Ceramic Coating Package" }, "promo_code": null, "refundable": false, "refunded_amount": 0.0, "refunded_at": null, "refunds": [], "resolutions": [], "retryable": true, "risk_score": null, "risk_signals": null, "settlement_amount": 50.0, "settlement_currency": "usd", "settlement_exchange_rate": null, "settlement_time_at": null, "shipment": null, "shipping_address": null, "status": "open", "substatus": "incomplete", "subtotal": 50.0, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "three_ds_verified": false, "total": 50.0, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": 50.0, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `shipment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount_after_fees": 50.0, "application_fee": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "card_brand": "visa", "card_exp_month": null, "card_exp_year": null, "card_last4": "4242", "checkout_configuration_id": null, "company": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "disputes": [], "failure_message": "Your card was declined.", "fees": [], "financing_installments_count": null, "financing_transactions": [], "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt": "2026-01-01T12:00:00.000Z", "member": { "id": "mber_xxxxxxxxxxxxxx", "phone": null }, "membership": { "id": "mem_xxxxxxxxxxxxxx", "phone_number": null, "status": "active" }, "metadata": {}, "needs_tracking": false, "next_payment_attempt": "2026-01-01T12:00:00.000Z", "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method": null, "payment_method_type": "card", "payments_failed": 1, "plan": { "id": "plan_xxxxxxxxxxxxxx", "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {}, "route": "ceramic-coating-package", "title": "Ceramic Coating Package" }, "promo_code": null, "refundable": false, "refunded_amount": 0.0, "refunded_at": null, "refunds": [], "resolutions": [], "retryable": true, "risk_score": null, "risk_signals": null, "settlement_amount": 50.0, "settlement_currency": "usd", "settlement_exchange_rate": null, "settlement_time_at": null, "shipment": null, "shipping_address": null, "status": "open", "substatus": "failed", "subtotal": 50.0, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "three_ds_verified": false, "total": 50.0, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": 50.0, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `shipment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount_after_fees": 50.0, "application_fee": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "card_brand": null, "card_exp_month": null, "card_exp_year": null, "card_last4": null, "checkout_configuration_id": null, "company": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "disputes": [], "failure_message": null, "fees": [], "financing_installments_count": null, "financing_transactions": [], "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt": null, "member": { "id": "mber_xxxxxxxxxxxxxx", "phone": null }, "membership": { "id": "mem_xxxxxxxxxxxxxx", "phone_number": null, "status": "active" }, "metadata": {}, "needs_tracking": false, "next_payment_attempt": null, "paid_at": null, "payment_instrument": { "card": null, "display_name": "ACH", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/ach/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/ach/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/ach/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/ach/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "us_bank_account" }, "payment_method": null, "payment_method_type": "us_bank_account", "payments_failed": 0, "plan": { "id": "plan_xxxxxxxxxxxxxx", "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {}, "route": "ceramic-coating-package", "title": "Ceramic Coating Package" }, "promo_code": null, "refundable": false, "refunded_amount": 0.0, "refunded_at": null, "refunds": [], "resolutions": [], "retryable": false, "risk_score": null, "risk_signals": null, "settlement_amount": 50.0, "settlement_currency": "usd", "settlement_exchange_rate": null, "settlement_time_at": null, "shipment": null, "shipping_address": null, "status": "pending", "substatus": "pending", "subtotal": 50.0, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "three_ds_verified": false, "total": 50.0, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": 50.0, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.pending" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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 - `shipment: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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount_after_fees": 50.0, "application_fee": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "card_brand": "visa", "card_exp_month": null, "card_exp_year": null, "card_last4": "4242", "checkout_configuration_id": null, "company": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "disputes": [], "failure_message": null, "fees": [], "financing_installments_count": null, "financing_transactions": [], "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt": null, "member": { "id": "mber_xxxxxxxxxxxxxx", "phone": null }, "membership": { "id": "mem_xxxxxxxxxxxxxx", "phone_number": null, "status": "active" }, "metadata": {}, "needs_tracking": false, "next_payment_attempt": null, "paid_at": "2026-01-01T12:00:00.000Z", "payment_instrument": { "card": { "brand": "visa", "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method": null, "payment_method_type": "card", "payments_failed": 0, "plan": { "id": "plan_xxxxxxxxxxxxxx", "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {}, "route": "ceramic-coating-package", "title": "Ceramic Coating Package" }, "promo_code": null, "refundable": true, "refunded_amount": 0.0, "refunded_at": null, "refunds": [], "resolutions": [], "retryable": false, "risk_score": null, "risk_signals": null, "settlement_amount": 50.0, "settlement_currency": "usd", "settlement_exchange_rate": null, "settlement_time_at": null, "shipment": null, "shipping_address": null, "status": "paid", "substatus": "succeeded", "subtotal": 50.0, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "three_ds_verified": false, "total": 50.0, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": 50.0, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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.created": { "post": { "description": "Sent when a payout is created (this event family replaces withdrawal.*)\n\nRequired permissions:\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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": "10.0", "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "destination_amount": null, "destination_currency": null, "estimated_arrival": null, "exchange_rate": null, "failure": null, "fee_amount": "0.0", "fee_paid_by": "self", "id": "wdrl_xxxxxxxxxxxxxx", "markup_fee": "0.0", "metadata": {}, "net_amount": "10.0", "notes": null, "object": "payout", "payer_name": null, "payout_method": { "nickname": "Shine Time business checking", "supported_payout_method": { "delivery_type": "bank_deposit", "icon_url": null, "payer_name": "Next Day Bank Deposit" } }, "payout_request_id": null, "source": null, "speed": "standard", "status": "in_review", "status_detail": "in_review", "trace_code": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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.created", "description": "The webhook event type", "example": "payout.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payout Created", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "payout.reversed": { "post": { "description": "Sent when a settled payout is reversed and the funds return to the balance (this event family replaces withdrawal.*)\n\nRequired permissions:\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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": "10.0", "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "destination_amount": null, "destination_currency": null, "estimated_arrival": null, "exchange_rate": null, "failure": { "code": null, "funds_returned_at": "2026-01-01T12:00:00.000Z", "message": null }, "fee_amount": "0.0", "fee_paid_by": "self", "id": "wdrl_xxxxxxxxxxxxxx", "markup_fee": "0.0", "metadata": {}, "net_amount": "10.0", "notes": null, "object": "payout", "payer_name": null, "payout_method": null, "payout_request_id": null, "source": null, "speed": "standard", "status": "reversed", "status_detail": "reversed", "trace_code": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout.reversed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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.reversed", "description": "The webhook event type", "example": "payout.reversed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payout Reversed", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "payout.updated": { "post": { "description": "Sent when a payout's status changes (this event family replaces withdrawal.*)\n\nRequired permissions:\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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": "10.0", "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "destination_amount": null, "destination_currency": null, "estimated_arrival": null, "exchange_rate": null, "failure": null, "fee_amount": "0.0", "fee_paid_by": "self", "id": "wdrl_xxxxxxxxxxxxxx", "markup_fee": "0.0", "metadata": {}, "net_amount": "10.0", "notes": null, "object": "payout", "payer_name": null, "payout_method": null, "payout_request_id": null, "source": null, "speed": "standard", "status": "completed", "status_detail": "completed", "trace_code": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a stablecoin payout it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled stablecoin payout can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the stablecoin conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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.updated", "description": "The webhook event type", "example": "payout.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payout Updated", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "address": { "city": "Austin", "country": "USA", "line1": "2201 Barton Springs Rd", "line2": "Suite 4", "postal_code": "78704", "state": "TX" }, "business_name": null, "business_representative": { "date_of_birth": "1988-04-12", "first_name": "Marcus", "last_name": "Webb", "middle_name": null }, "email": "marcus@shinetime.example", "id": "poact_xxxxxxxxxxxxxx", "latest_verification": null, "phone": "+1 512 555 0194", "status": "connected" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout_account.status_updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/PayoutAccount" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account_reference": "4483", "bank_verification_state": "no_data", "created_at": "2026-01-01T12:00:00.000Z", "destination_currency": "usd", "estimated_arrival": null, "fee_structure": null, "id": "potk_xxxxxxxxxxxxxx", "institution_name": "Frost Bank", "is_clone": false, "is_default": true, "last_paid_out_at": null, "linked_via_plaid": false, "needs_plaid_reconnect": false, "nickname": "Shine Time business checking", "object": "payout_method", "payer_name": "Next Day Bank Deposit", "quote": null, "status": "created", "status_reason": null, "supported_payout_method": { "country_code": "USA", "delivery_type": "bank_deposit", "icon_url": null, "name": "Next Day Bank Deposit", "supports_instant_delivery": false, "supports_plaid": true, "supports_standard_delivery": true }, "unavailable_reason": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout_method.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "account_reference": { "description": "Masked identifier for the destination, such as the last four digits of a bank account.", "example": "••••6789", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "verified", "type": [ "string", "null" ] }, "created_at": { "description": "When the payout method was added.", "example": "2026-06-15T09:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "description": "Currency payouts are delivered in for this method.", "example": "usd", "type": "string" }, "estimated_arrival": { "description": "Estimated arrival times before an amount-specific quote is requested. Null when the method is not currently eligible.", "properties": { "instant": { "description": "Estimated instant-delivery arrival, or null when unavailable.", "example": "2026-07-30T12:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "standard": { "description": "Estimated standard-delivery arrival, or null when unavailable.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "standard", "instant" ], "type": [ "object", "null" ] }, "fee_structure": { "description": "Configured fee terms for this payout method. Null when the method is not currently eligible. An amount-specific quote remains authoritative.", "properties": { "currency": { "description": "Currency code of fixed_amount.", "example": "usd", "type": "string" }, "fixed_amount": { "description": "Fixed fee charged, denominated in `currency`.", "example": 0.25, "format": "float", "type": "number" }, "percentage": { "description": "Percentage of the payout amount charged as a fee.", "example": 0.0, "format": "float", "type": "number" } }, "required": [ "percentage", "fixed_amount", "currency" ], "type": [ "object", "null" ] }, "id": { "description": "Payout method ID.", "example": "pyot_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "Name of the bank or institution receiving payouts.", "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "description": "Whether this is the default payout method for the account.", "example": true, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "example": "2026-08-02T15:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Business checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "description": "Display name of the payout rail, such as `ACH Bank Deposit`.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Fee and delivery estimate for paying out the requested amount through this method. Null unless an amount was provided, or when the estimate is unavailable.", "properties": { "amount": { "description": "The payout amount the quote is for.", "example": 500.0, "format": "float", "type": "number" }, "currency": { "description": "Currency of the quoted amount.", "example": "usd", "type": "string" }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency.", "example": 1.0, "format": "float", "type": "number" }, "instant": { "description": "Instant-delivery estimate. Null if the method does not support instant delivery, instant delivery is unavailable for the account, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 5.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 494.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] }, "max_limit": { "description": "Maximum payout amount for this method, in the payout currency.", "example": 25000.0, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount for this method, in the payout currency.", "example": 1.0, "format": "float", "type": "number" }, "standard": { "description": "Standard-delivery estimate. Null if the method does not support standard delivery, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 0.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 499.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] } }, "required": [ "amount", "currency", "exchange_rate", "min_limit", "max_limit", "standard", "instant" ], "type": [ "object", "null" ] }, "status": { "description": "Lifecycle status: `created` means saved but unused, `active` means a payout succeeded through it, `broken` means a payout failure disabled it; a later successful payout returns it to `active`.", "enum": [ "created", "active", "broken" ], "example": "active", "type": "string" }, "status_reason": { "description": "Machine-readable code for why the method is `broken` — the newest disabling failure recorded through it, whether a payout error or a pre-payout rejection. `null` unless the method is broken, or when it was disabled without a recorded failure.", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "The supported payout method this saved method was created from.", "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "country_code", "supports_standard_delivery", "supports_instant_delivery", "supports_plaid" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "bank_verification_state", "linked_via_plaid", "needs_plaid_reconnect", "is_clone", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "PayoutMethod Created", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "plan.created": { "post": { "description": "Sent when a plan is created\n\nRequired permissions:\n - `webhook_receive:plans`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "billing_period": 30, "cancel_discount_intervals": null, "cancel_discount_percentage": null, "checkout_styling": null, "collect_tax": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "custom_fields": [], "deletable": true, "description": "One maintenance wash per week, any vehicle on file.", "effective_payment_method_configuration": { "disabled": [], "enabled": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "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", "modo", "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", "rapipago", "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" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0.0, "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "invoice": null, "member_count": 0, "metadata": {}, "offer_cancel_discount": false, "payment_method_configuration": null, "plan_type": "renewal", "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50.0, "split_pay_required_payments": null, "stock": 0, "strike_through_initial_price": null, "strike_through_renewal_price": null, "tax_type": "unspecified", "three_ds_level": null, "title": "Unlimited Wash Club", "trial_period_days": null, "unlimited_stock": false, "updated_at": "2026-01-01T12:00:00.000Z", "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "plan.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Plan" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "plan.created", "description": "The webhook event type", "example": "plan.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Plan Created", "tags": [ "Plans" ] }, "x-whop-surface": "native" }, "plan.deleted": { "post": { "description": "Sent when a plan is deleted\n\nRequired permissions:\n - `webhook_receive:plans`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "billing_period": 30, "cancel_discount_intervals": null, "cancel_discount_percentage": null, "checkout_styling": null, "collect_tax": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "custom_fields": [], "deletable": true, "description": "One maintenance wash per week, any vehicle on file.", "effective_payment_method_configuration": { "disabled": [], "enabled": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "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", "modo", "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", "rapipago", "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" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0.0, "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "invoice": null, "member_count": 0, "metadata": {}, "offer_cancel_discount": false, "payment_method_configuration": null, "plan_type": "renewal", "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50.0, "split_pay_required_payments": null, "stock": 0, "strike_through_initial_price": null, "strike_through_renewal_price": null, "tax_type": "unspecified", "three_ds_level": null, "title": "Unlimited Wash Club", "trial_period_days": null, "unlimited_stock": false, "updated_at": "2026-01-01T12:00:00.000Z", "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "plan.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Plan" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "plan.deleted", "description": "The webhook event type", "example": "plan.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Plan Deleted", "tags": [ "Plans" ] }, "x-whop-surface": "native" }, "plan.updated": { "post": { "description": "Sent when a plan is updated\n\nRequired permissions:\n - `webhook_receive:plans`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "billing_period": 30, "cancel_discount_intervals": null, "cancel_discount_percentage": null, "checkout_styling": null, "collect_tax": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "custom_fields": [], "deletable": true, "description": "One maintenance wash per week, any vehicle on file.", "effective_payment_method_configuration": { "disabled": [], "enabled": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "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", "modo", "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", "rapipago", "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" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0.0, "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "invoice": null, "member_count": 0, "metadata": {}, "offer_cancel_discount": false, "payment_method_configuration": null, "plan_type": "renewal", "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50.0, "split_pay_required_payments": null, "stock": 0, "strike_through_initial_price": null, "strike_through_renewal_price": null, "tax_type": "unspecified", "three_ds_level": null, "title": "Unlimited Wash Club", "trial_period_days": 7, "unlimited_stock": false, "updated_at": "2026-01-01T12:00:00.000Z", "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "plan.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Plan" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "plan.updated", "description": "The webhook event type", "example": "plan.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Plan Updated", "tags": [ "Plans" ] }, "x-whop-surface": "native" }, "product.created": { "post": { "description": "Sent when a product is created\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "product.created", "description": "The webhook event type", "example": "product.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Created", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "product.deleted": { "post": { "description": "Sent when a product is deleted\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "product.deleted", "description": "The webhook event type", "example": "product.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Deleted", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "product.published": { "post": { "description": "Sent when a product is published\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "live_marketplace", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.published" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "product.published", "description": "The webhook event type", "example": "product.published", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Published", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "product.unpublished": { "post": { "description": "Sent when a product is unpublished\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "verified": false, "visibility": "hidden" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.unpublished" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "product.unpublished", "description": "The webhook event type", "example": "product.unpublished", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Unpublished", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "product.updated": { "post": { "description": "Sent when a product is updated\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "product.updated", "description": "The webhook event type", "example": "product.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Updated", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": 50.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "rf_xxxxxxxxxxxxxx", "payment": { "billing_reason": null, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "dispute_alerted_at": null, "id": "pay_xxxxxxxxxxxxxx", "member": null, "membership": { "id": "mem_xxxxxxxxxxxxxx", "status": "active" }, "metadata": {}, "paid_at": "2026-01-01T12:00:00.000Z", "payment_method_type": null, "plan": { "id": "plan_xxxxxxxxxxxxxx", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {} }, "subtotal": null, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "total": null, "usd_total": null, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "provider": "stripe", "provider_created_at": "2026-01-01T12:00:00.000Z", "reference_status": null, "reference_type": null, "reference_value": null, "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "refund.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Refund" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": 50.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "rf_xxxxxxxxxxxxxx", "payment": { "billing_reason": null, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "dispute_alerted_at": null, "id": "pay_xxxxxxxxxxxxxx", "member": null, "membership": { "id": "mem_xxxxxxxxxxxxxx", "status": "active" }, "metadata": {}, "paid_at": "2026-01-01T12:00:00.000Z", "payment_method_type": null, "plan": { "id": "plan_xxxxxxxxxxxxxx", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {} }, "subtotal": null, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "total": null, "usd_total": null, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "provider": "stripe", "provider_created_at": "2026-01-01T12:00:00.000Z", "reference_status": "available", "reference_type": "acquirer_reference_number", "reference_value": "74850120752", "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "refund.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Refund" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 0.0, "available_actions": [ "accept", "deny", "request_info" ], "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_appealed": false, "escalated": false, "id": "reso_xxxxxxxxxxxxxx", "outcome": null, "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": null, "response_due_at": "2026-01-01T12:00:00.000Z", "status": "awaiting_merchant", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "resolution_center_case.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 0.0, "available_actions": [], "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_appealed": false, "escalated": false, "id": "reso_xxxxxxxxxxxxxx", "outcome": "customer_won", "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": "merchant", "response_due_at": null, "status": "closed", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "resolution_center_case.decided" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 0.0, "available_actions": [], "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_appealed": false, "escalated": false, "id": "reso_xxxxxxxxxxxxxx", "outcome": null, "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": null, "response_due_at": "2026-01-01T12:00:00.000Z", "status": "awaiting_customer", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "resolution_center_case.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "checkout_configuration": null, "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "error_message": "Your card was declined.", "id": "sint_xxxxxxxxxxxxxx", "member": { "id": "mber_xxxxxxxxxxxxxx", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "metadata": null, "payment_method": null, "status": "canceled", "three_ds_verified": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "setup_intent.canceled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "checkout_configuration": null, "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "error_message": null, "id": "sint_xxxxxxxxxxxxxx", "member": { "id": "mber_xxxxxxxxxxxxxx", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "metadata": null, "payment_method": null, "status": "requires_action", "three_ds_verified": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "setup_intent.requires_action" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "checkout_configuration": null, "company": { "id": "biz_xxxxxxxxxxxxxx" }, "created_at": "2026-01-01T12:00:00.000Z", "error_message": null, "id": "sint_xxxxxxxxxxxxxx", "member": { "id": "mber_xxxxxxxxxxxxxx", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "metadata": null, "payment_method": { "card": { "brand": null, "exp_month": 11, "exp_year": 2030, "last4": "4242" }, "created_at": "2026-01-01T12:00:00.000Z", "id": "payt_xxxxxxxxxxxxxx", "mailing_address": null, "payment_method_type": "card" }, "status": "succeeded", "three_ds_verified": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "setup_intent.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] } }, "shipment.created": { "post": { "description": "Sent when a shipment is created\n\nRequired permissions:\n - `shipment:basic:read`\n - `payment:basic:read`\n - `webhook_receive:shipments`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "carrier": "ups", "checkpoints": [], "created_at": "2026-01-01T12:00:00.000Z", "id": "ship_xxxxxxxxxxxxxx", "payment_id": "pay_xxxxxxxxxxxxxx", "status": "pre_transit", "tracking_number": "1Z999AA10123456784", "tracking_url": "https://track.aftership.com/trk_xxxxxxxxxxxxxxxxxxxxxxxx", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "shipment.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Shipment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "shipment.created", "description": "The webhook event type", "example": "shipment.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Shipment Created", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "shipment.updated": { "post": { "description": "Sent when a shipment is updated\n\nRequired permissions:\n - `shipment:basic:read`\n - `payment:basic:read`\n - `webhook_receive:shipments`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "carrier": "ups", "checkpoints": [], "created_at": "2026-01-01T12:00:00.000Z", "id": "ship_xxxxxxxxxxxxxx", "payment_id": "pay_xxxxxxxxxxxxxx", "status": "delivered", "tracking_number": "1Z999AA10123456784", "tracking_url": "https://track.aftership.com/trk_xxxxxxxxxxxxxxxxxxxxxxxx", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "shipment.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Shipment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "shipment.updated", "description": "The webhook event type", "example": "shipment.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Shipment Updated", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "swap.completed": { "post": { "description": "Sent when a swap is completed\n\nRequired permissions:\n - `webhook_receive:swaps`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "object": "account", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": "2375000000", "available_at": "2026-01-01T12:00:00.000Z", "currency": { "code": "usd", "precision": "100000000" }, "id": "line_3", "ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "line_type": "payment_gross", "object": "ledger_activity", "payment": { "amount": { "amount": "-2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "card_brand": "some_string", "card_last4": "some_string", "created_at": "some_string", "id": "some_string", "object": "payment", "payment_method_type": "some_string", "payment_processor": "some_string", "plan": { "id": "some_string", "name": "some_string" }, "product": { "id": "some_string", "name": "some_string" }, "user": { "email": "some_string", "id": "some_string", "name": "some_string" } }, "payment_id": "some_string", "plan_id": "some_string", "plan_name": "some_string", "posted_at": "2026-01-01T12:00:00.000Z", "product_id": "some_string", "product_name": "some_string", "resource": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "object": "account", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "source": { "amount_float": 1500.0, "card_brand": "some_string", "chain": "plasma", "claim_url": "https://whop.com/claim", "created_at": "2026-01-01T12:00:00.000Z", "estimated_arrival": "2026-01-01T12:00:00.000Z", "from_amount": "502.51", "from_currency": "usdt", "id": "airdrp_xxxxxxxxxxxxxx", "object": "airdrop_link", "payer_name": "MassPay", "payment_amount": { "amount": "-2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "payment_method_type": "some_string", "payment_processor": "some_string", "payout_destination": { "icon_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-activity-icon", "payer_name": "ACH Bank Deposit" }, "payout_token_nickname": "Ops checking", "reason": "bounty_payout", "risk_review_hold": false, "sender_address": "0x8a4de51b9c37f2e6a0d1b8c94e5f7a2d3c6b0e19", "status": "fully_claimed", "to_amount": "500.0", "to_currency": "usd", "tx_hash": "0x5d84a1c7e2f9b036d48c5a7e1b9f2d6c3a8e0b4f7c1d9e5a2b6f8c0d3e7a1b52" }, "user_email": "some_string", "user_id": "some_string", "user_name": "some_string" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "swap.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerActivity" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "swap.completed", "description": "The webhook event type", "example": "swap.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Swap Completed", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "transfer.completed": { "post": { "description": "Sent when a transfer is completed\n\nRequired permissions:\n - `webhook_receive:transfers`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": 250.0, "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "currency": "usd", "destination": { "id": "biz_xxxxxxxxxxxxx2", "route": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing", "typename": "Company" }, "destination_ledger_account_id": "ldgr_xxxxxxxxxxxxx2", "failed_at": null, "failure_code": null, "failure_reason": null, "fee_amount": 7.5, "id": "ctt_xxxxxxxxxxxxxx", "metadata": { "invoice": "SHINE-1042" }, "notes": "Detailing supplies restock", "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "origin_ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "transfer.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25.0, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "null" ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "title": "Transfer", "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "transfer.completed", "description": "The webhook event type", "example": "transfer.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Transfer Completed", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "transfer.created": { "post": { "description": "Sent when a transfer is created\n\nRequired permissions:\n - `webhook_receive:transfers`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": 250.0, "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "currency": "usd", "destination": { "id": "biz_xxxxxxxxxxxxx2", "route": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing", "typename": "Company" }, "destination_ledger_account_id": "ldgr_xxxxxxxxxxxxx2", "failed_at": null, "failure_code": null, "failure_reason": null, "fee_amount": 7.5, "id": "ctt_xxxxxxxxxxxxxx", "metadata": { "invoice": "SHINE-1042" }, "notes": "Detailing supplies restock", "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "origin_ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "transfer.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25.0, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "null" ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "title": "Transfer", "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "transfer.created", "description": "The webhook event type", "example": "transfer.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Transfer Created", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "transfer.failed": { "post": { "description": "Sent when a transfer is failed\n\nRequired permissions:\n - `webhook_receive:transfers`", "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "amount": 10.0, "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "currency": "usd", "destination": { "id": "biz_xxxxxxxxxxxxx2", "route": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing", "typename": "Company" }, "destination_ledger_account_id": "ldgr_xxxxxxxxxxxxx2", "failed_at": null, "failure_code": null, "failure_reason": null, "fee_amount": null, "id": "ctt_xxxxxxxxxxxxxx", "metadata": null, "notes": null, "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "origin_ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "transfer.failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25.0, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "null" ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "title": "Transfer", "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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": "transfer.failed", "description": "The webhook event type", "example": "transfer.failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Transfer Failed", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "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": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-08-25-2", "data": { "id": "verf_xxxxxxxxxxxxxx", "last_error_code": null, "last_error_reason": null, "status": "verified" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "verification.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Verification" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "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", "api_version_date", "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" ] } } }, "x-tagGroups": [ { "description": "The accounts and people everything else hangs off.", "name": "Core Resources", "tags": [ "Accounts", "Users", "Team Members", "Members", "Webhooks", "Stats", "Verifications", "Exports" ] }, { "description": "What users get told about, and how they tune it.", "name": "Notifications", "tags": [ "Notifications" ] }, { "description": "Balances and every way funds move in or out.", "name": "Money", "tags": [ "Payments", "Confirmation Tokens", "Setup Intents", "Ledgers", "Payouts", "Cards", "Transfers", "Disputes", "Dispute alerts", "Deposits", "Swaps", "Resolution Center Cases" ] }, { "description": "Sell products and get paid.", "name": "Commerce", "tags": [ "Products", "Plans", "Promo Codes", "Memberships", "Checkout Configurations", "Payment Method Domains", "Shipments" ] }, { "description": "Refer users and businesses to Whop and track what you earn.", "name": "Partners", "tags": [ "Partners" ] }, { "description": "Post paid tasks and pay people for completed work.", "name": "Workforce", "tags": [ "Bounties", "Bounty Submissions" ] }, { "description": "Who visits and what converts, captured by the pixel.", "name": "Tracking", "tags": [ "People", "Events", "Reports", "Recommended Actions" ] }, { "description": "Run and measure ad campaigns from your integration.", "name": "Ads", "tags": [ "Ads", "Ad Campaigns", "Ad Groups", "Audiences" ] }, { "description": "Generate media assets from your integration.", "name": "Media", "tags": [ "Files", "Media" ] }, { "description": "Accounts connected from other platforms.", "name": "Identity", "tags": [ "Social Accounts" ] }, { "description": "Build, host, and observe apps on the Whop platform.", "name": "Developer", "tags": [ "Apps", "App Builds", "API Keys", "Api Logs", "Permissions", "Experiments" ] } ] }