{"openapi":"3.1.0","info":{"title":"Bitcoin Rewards Affiliate API","version":"1.3.0","description":"The Bitcoin Rewards Affiliate API allows you to programmatically access your affiliated businesses,\nrewards configurations, and pre-built referral links.\n\n## Authentication\n\nAll API requests require a valid API key passed in the `Authorization` header:\n\n```\nAuthorization: Bearer sk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nAPI keys can be created and managed in your [Affiliate Dashboard](/developers).\n\n## Rate Limits\n\nAPI requests are rate limited to 100 requests per minute per API key.\n\n## Errors\n\nThe API uses standard HTTP status codes:\n\n| Status | Description |\n|--------|-------------|\n| 200 | Success |\n| 401 | Unauthorized - Invalid or missing API key |\n| 500 | Internal server error |\n","contact":{"name":"Oshi Support","url":"https://oshi.tech","email":"support@oshi.tech"},"license":{"name":"Proprietary","url":"https://oshi.tech/legal/terms"}},"servers":[{"url":"https://www.bitcoinrewards.app","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"Authentication","description":"Validate API keys and check access"},{"name":"Businesses","description":"Access affiliated business data and referral links"},{"name":"Public","description":"Public endpoints for SEO and discovery (no authentication required)"},{"name":"Webhooks","description":"Outbound events Oshi POSTs to your endpoints (Standard Webhooks signing).\nManage endpoints under Developers → Webhooks. Guide: /docs/guides/webhooks\n"}],"paths":{"/api/key-test":{"get":{"operationId":"testApiKey","summary":"Test API Key","description":"Validates your API key and returns metadata about the key.\nUse this endpoint to verify your API key is working correctly.\n","tags":["Authentication"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"API key is valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyTestResponse"},"example":{"success":true,"message":"API key is valid","key":{"id":42,"name":"My Production Key","affiliateId":"123456","readOnly":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_header":{"summary":"Missing authorization header","value":{"error":"Missing authorization header"}},"invalid_format":{"summary":"Invalid API key format","value":{"error":"Invalid API key format"}},"invalid_key":{"summary":"Invalid API key","value":{"error":"Invalid API key"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/get-business-rewards":{"get":{"operationId":"getBusinessRewards","summary":"Get Business Rewards","description":"Returns all businesses you're affiliated with, including:\n- Business details (name, description, images, branding)\n- Simplified rewards info (headline %, base %, VIP tiers)\n- Products with categories\n- Pre-built referral URLs ready for immediate use\n- Ready-to-use display text for your UI\n\nThe response is optimized for display—percentages are calculated,\nURLs are fully constructed, and copy text is ready to use.\n","tags":["Businesses"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of affiliated businesses with rewards","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Business"}},"examples":{"percentage_reward":{"summary":"Percentage-based reward","value":[{"slug":"amazon","updatedAt":"2024-01-15T10:30:00.000Z","name":"Amazon","shortDescription":"Shop millions of products","logoUrl":"https://example.com/amazon-logo.png","transparentLogoUrl":"https://example.com/amazon-logo-transparent.png","coverUrl":"https://example.com/amazon-cover.jpg","coverDominantColor":"#232F3E","affiliateOverlayLogoUrl":null,"squareImageUrl":"https://example.com/amazon-square.png","squareImageDominantColor":"#FF9900","visibleCategories":["Electronics","Home & Garden","Fashion"],"website":"https://amazon.com","isOnline":true,"isFeatured":true,"rewards":{"headlinePercent":5,"headlineFixed":null,"isFixedReward":false,"basePercent":3,"maxPercent":8,"hasVipTiers":true,"hasReferralBonus":true,"minimumPurchase":null},"rewardsSummary":{"basePercentage":3,"maxPercentage":8,"hasVipTiers":true,"isFixedReward":false,"headlineFixed":null,"minimumPurchase":null,"referralBonus":2,"socialRewardsEnabled":true,"socialRewardsTotalSats":500,"btcPayBonusEnabled":false,"btcPayBonus":null,"hasRedemptionOffers":false,"redemptionMaxMultiplier":null,"wineClubBonusEnabled":false,"wineClubBonusPercentage":null},"products":[{"id":"prod_123","productId":"ext_456","productType":"Electronics","title":"Echo Dot","image":"https://example.com/echo.jpg","price":49.99,"handle":"echo-dot","collections":["Best Sellers"],"isFeatured":false}],"productCount":1,"categories":["Electronics","Home & Garden"],"socialLinks":[{"platform":"Instagram","url":"https://instagram.com/amazon"}],"whyShopHere":"Largest online marketplace with fast shipping","isCurrentlyOfferingRewards":true,"referralUrl":"https://amazon.com?ref=ABC123&utm_source=oshi&utm_medium=referral&utm_campaign=ref_ABC123&ttl=7776000&policy=first","handoffUrl":"https://oshi.link/ABC123","affiliateSignupUrl":"https://oshi.link/a/abc123def456","referralCode":"ABC123","attributionPeriodDays":90,"affiliateCode":"ABC123","affiliatePercentage":10,"affiliateRewards":{"referringReward":10,"referringRewardType":"percentage","referredReward":5,"referredRewardType":"percentage","minimumPurchase":null,"lifetimeCommission":2,"lifetimeCommissionType":"percentage"},"affiliateSince":"2024-01-01T00:00:00.000Z"}]},"fixed_reward":{"summary":"Fixed dollar amount reward","value":[{"slug":"pubkey","updatedAt":"2024-01-15T10:30:00.000Z","name":"PubKey","shortDescription":"Bitcoin bar and restaurant","logoUrl":"https://example.com/pubkey-logo.png","transparentLogoUrl":null,"coverUrl":"https://example.com/pubkey-cover.jpg","coverDominantColor":"#F7931A","affiliateOverlayLogoUrl":null,"squareImageUrl":null,"squareImageDominantColor":null,"visibleCategories":[],"website":"https://pubkey.bar","isOnline":false,"isFeatured":false,"rewards":{"headlinePercent":0,"headlineFixed":30,"isFixedReward":true,"basePercent":5,"maxPercent":5,"hasVipTiers":false,"hasReferralBonus":true,"minimumPurchase":100},"rewardsSummary":{"basePercentage":5,"maxPercentage":5,"hasVipTiers":false,"isFixedReward":true,"headlineFixed":30,"minimumPurchase":100,"referralBonus":null,"socialRewardsEnabled":false,"socialRewardsTotalSats":0,"btcPayBonusEnabled":false,"btcPayBonus":null,"hasRedemptionOffers":false,"redemptionMaxMultiplier":null,"wineClubBonusEnabled":false,"wineClubBonusPercentage":null},"products":[],"productCount":0,"categories":[],"socialLinks":[],"whyShopHere":"NYC's premier Bitcoin bar","isCurrentlyOfferingRewards":true,"referralUrl":"https://pubkey.bar?ref=XYZ789&utm_source=oshi&utm_medium=referral&utm_campaign=ref_XYZ789&ttl=7776000&policy=first","handoffUrl":"https://oshi.link/XYZ789","affiliateSignupUrl":"https://oshi.link/a/xyz789abc123","referralCode":"XYZ789","attributionPeriodDays":90,"affiliateCode":"XYZ789","affiliatePercentage":15,"affiliateRewards":{"referringReward":15,"referringRewardType":"percentage","referredReward":30,"referredRewardType":"fixed","minimumPurchase":100,"lifetimeCommission":null,"lifetimeCommissionType":"percentage"},"affiliateSince":"2024-06-01T00:00:00.000Z"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/businesses":{"get":{"operationId":"listPublicBusinesses","summary":"List All Businesses","description":"Returns a paginated list of all active businesses with Bitcoin rewards.\nThis is a public endpoint—no authentication required.\n\nUsed for SEO pages, discovery, and building business directories.\n\n**Note:** The `referralCode`, `referralUrl`, and `handoffUrl` fields return\nOshi's affiliate tracking links. Purchases through these links attribute\nto Oshi's affiliate account. For your own affiliate tracking, use the\nauthenticated `/api/get-business-rewards` endpoint.\n","tags":["Public"],"security":[],"parameters":[{"name":"limit","in":"query","description":"Maximum number of businesses to return (1-500)","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","description":"Number of businesses to skip for pagination","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"List of businesses with rewards summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBusinessListResponse"},"example":{"businesses":[{"slug":"amazon","updatedAt":"2024-01-15T10:30:00.000Z","name":"Amazon","shortDescription":"Shop millions of products","logoUrl":"https://example.com/amazon-logo.png","transparentLogoUrl":"https://example.com/amazon-logo-transparent.png","affiliateOverlayLogoUrl":null,"coverUrl":"https://example.com/amazon-cover.jpg","squareImageUrl":"https://example.com/amazon-square.png","coverDominantColor":"#232F3E","squareImageDominantColor":"#FF9900","website":"https://amazon.com","isOnline":true,"isFeatured":true,"referralCode":"OSHI123","attributionPeriodDays":90,"referralUrl":"https://amazon.com?ref=OSHI123&utm_source=oshi&utm_medium=referral&utm_campaign=ref_OSHI123&ttl=7776000&policy=first","handoffUrl":"https://oshi.link/OSHI123","affiliateSignupUrl":"https://oshi.link/a/abc123def456","rewardsSummary":{"basePercentage":3,"maxPercentage":8,"hasVipTiers":true},"productCount":25}],"pagination":{"total":150,"limit":100,"offset":0,"hasMore":true}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/businesses/{slug}":{"get":{"operationId":"getPublicBusinessBySlug","summary":"Get Business Details","description":"Returns detailed information about a specific business including\nfull rewards configuration, products, and social links.\nThis is a public endpoint—no authentication required.\n\nUsed for SEO business detail pages.\n\n**Note:** The `referralCode`, `referralUrl`, and `handoffUrl` fields return\nOshi's affiliate tracking links. For your own affiliate tracking, use the\nauthenticated API.\n","tags":["Public"],"security":[],"parameters":[{"name":"slug","in":"path","required":true,"description":"URL-friendly business identifier","schema":{"type":"string"},"example":"amazon"}],"responses":{"200":{"description":"Full business details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBusinessDetail"}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Business not found"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"commission.created":{"post":{"operationId":"webhook_commission_created","summary":"Commission created","description":"A commission was recorded for an attributed order (lifetime, repeat purchase, or manual).","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"commission.created"},"data":{"$ref":"#/components/schemas/WebhookCommissionCreatedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"commission.created","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"commission":{"id":"com_5179b350ece051a39f0d8c75","status":"pending","source":"lifetime","amount_sats":4200,"commission_percentage":10,"created_at":"2026-10-23T11:00:00Z","paid_at":null,"available_at":null},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"order":{"id":"5829104773185","number":"#1042","subtotal":"84.00","currency":"USD","created_at":"2026-10-23T10:58:12Z"},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"commission.paid":{"post":{"operationId":"webhook_commission_paid","summary":"Commission paid","description":"The commission was funded into your wallet. It stays locked until the brand's lockup period ends.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"commission.paid"},"data":{"$ref":"#/components/schemas/WebhookCommissionPaidData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"commission.paid","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"commission":{"id":"com_5179b350ece051a39f0d8c75","status":"paid","source":"lifetime","amount_sats":4200,"commission_percentage":10,"created_at":"2026-10-23T11:00:00Z","paid_at":"2026-10-23T11:05:00Z","available_at":null},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"order":{"id":"5829104773185","number":"#1042","subtotal":"84.00","currency":"USD","created_at":"2026-10-23T10:58:12Z"},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"commission.available":{"post":{"operationId":"webhook_commission_available","summary":"Commission available","description":"The lockup period has passed and the commission can be withdrawn.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"commission.available"},"data":{"$ref":"#/components/schemas/WebhookCommissionAvailableData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"commission.available","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"commission":{"id":"com_5179b350ece051a39f0d8c75","status":"available","source":"lifetime","amount_sats":4200,"commission_percentage":10,"created_at":"2026-10-23T11:00:00Z","paid_at":"2026-10-23T11:05:00Z","available_at":"2026-11-22T11:00:00Z"},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"order":{"id":"5829104773185","number":"#1042","subtotal":"84.00","currency":"USD","created_at":"2026-10-23T10:58:12Z"},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"commission.reversed":{"post":{"operationId":"webhook_commission_reversed","summary":"Commission reversed","description":"All or part of a commission was clawed back (refund, cancellation, manual adjustment, or fraud).","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"commission.reversed"},"data":{"$ref":"#/components/schemas/WebhookCommissionReversedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"commission.reversed","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"commission":{"id":"com_5179b350ece051a39f0d8c75","status":"reversed","source":"lifetime","amount_sats":4200,"commission_percentage":10,"created_at":"2026-10-23T11:00:00Z","paid_at":"2026-10-23T11:05:00Z","available_at":null},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"order":{"id":"5829104773185","number":"#1042","subtotal":"84.00","currency":"USD","created_at":"2026-10-23T10:58:12Z"},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e","reversal":{"id":"rev_b5cbf5ab0401a0221d078f96","amount_sats":2100,"partial":true,"reason":"refund"}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"referral.created":{"post":{"operationId":"webhook_referral_created","summary":"Referral created","description":"A new customer was attributed to you for the first time at a brand.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"referral.created"},"data":{"$ref":"#/components/schemas/WebhookReferralCreatedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"referral.created","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"referral":{"id":"rfl_10b2b5b1d2f9ad90bafd8810","created_at":"2026-10-23T10:58:30Z"},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"referral.reward_paid":{"post":{"operationId":"webhook_referral_reward_paid","summary":"Referral reward paid","description":"The first-purchase referral reward for a customer you referred was paid to you.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"referral.reward_paid"},"data":{"$ref":"#/components/schemas/WebhookReferralRewardPaidData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"referral.reward_paid","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"referral":{"id":"rfl_10b2b5b1d2f9ad90bafd8810"},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"amount_sats":1500,"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"order.attributed":{"post":{"operationId":"webhook_order_attributed","summary":"Order attributed","description":"An order was attributed to you, even if it earns no commission (commission_sats is null then).","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"order.attributed"},"data":{"$ref":"#/components/schemas/WebhookOrderAttributedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"order.attributed","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"order":{"id":"5829104773185","number":"#1042","subtotal":"84.00","currency":"USD","created_at":"2026-10-23T10:58:12Z"},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e","attribution":"first_purchase","commission_sats":4200}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"order.refunded":{"post":{"operationId":"webhook_order_refunded","summary":"Order refunded","description":"An attributed order was refunded or cancelled, fully or partially.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"order.refunded"},"data":{"$ref":"#/components/schemas/WebhookOrderRefundedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"order.refunded","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"order":{"id":"5829104773185","number":"#1042","subtotal":"84.00","currency":"USD","created_at":"2026-10-23T10:58:12Z"},"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"customer_ref":"cus_3f9a1c0b7e2d4a6f8b1c9d0e","refund_type":"partial"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"withdrawal.created":{"post":{"operationId":"webhook_withdrawal_created","summary":"Withdrawal created","description":"A withdrawal was requested from the affiliate portal, the rewards app, or an auto-withdrawal.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"withdrawal.created"},"data":{"$ref":"#/components/schemas/WebhookWithdrawalCreatedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"withdrawal.created","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"withdrawal":{"id":"wd_ea00b51f15a2f184bff9b803","status":"pending","amount_sats":25000,"destination_type":"lightning_address","destination_masked":"s***@getalby.com","origin":"affiliate_portal","created_at":"2026-10-23T12:00:00Z","completed_at":null,"failure":null}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"withdrawal.completed":{"post":{"operationId":"webhook_withdrawal_completed","summary":"Withdrawal completed","description":"The Lightning payment for a withdrawal was confirmed.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"withdrawal.completed"},"data":{"$ref":"#/components/schemas/WebhookWithdrawalCompletedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"withdrawal.completed","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"withdrawal":{"id":"wd_ea00b51f15a2f184bff9b803","status":"completed","amount_sats":25000,"destination_type":"lightning_address","destination_masked":"s***@getalby.com","origin":"affiliate_portal","created_at":"2026-10-23T12:00:00Z","completed_at":"2026-10-23T12:00:41Z","failure":null}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"withdrawal.failed":{"post":{"operationId":"webhook_withdrawal_failed","summary":"Withdrawal failed","description":"A withdrawal failed and the sats were returned to your wallet.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"withdrawal.failed"},"data":{"$ref":"#/components/schemas/WebhookWithdrawalFailedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"withdrawal.failed","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"withdrawal":{"id":"wd_ea00b51f15a2f184bff9b803","status":"failed","amount_sats":25000,"destination_type":"lightning_address","destination_masked":"s***@getalby.com","origin":"affiliate_portal","created_at":"2026-10-23T12:00:00Z","completed_at":null,"failure":{"code":"NO_ROUTE","message":"Could not find a route to the destination."}}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"program.joined":{"post":{"operationId":"webhook_program_joined","summary":"Program joined","description":"You joined a brand's affiliate program (automatically, by approval, or by import).","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"program.joined"},"data":{"$ref":"#/components/schemas/WebhookProgramJoinedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"program.joined","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"membership":{"id":"mem_7b1a1d043ee66d23f0967b28","code":"JANE10","link":"https://example-coffee.com/?ref=JANE10","discount_code":"JANE10","is_oshi_network":false,"joined_via":"approved"}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"program.application_denied":{"post":{"operationId":"webhook_program_application_denied","summary":"Application denied","description":"A brand declined your application to its affiliate program.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"program.application_denied"},"data":{"$ref":"#/components/schemas/WebhookProgramApplicationDeniedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"program.application_denied","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"application":{"id":"app_cb5dc7d15281de961eb9bae8"}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"program.removed":{"post":{"operationId":"webhook_program_removed","summary":"Removed from program","description":"A brand removed you from its affiliate program.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"program.removed"},"data":{"$ref":"#/components/schemas/WebhookProgramRemovedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"program.removed","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"membership":{"id":"mem_7b1a1d043ee66d23f0967b28","code":"JANE10"}}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"discount_code.approved":{"post":{"operationId":"webhook_discount_code_approved","summary":"Discount code approved","description":"A brand approved the discount code you requested.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"discount_code.approved"},"data":{"$ref":"#/components/schemas/WebhookDiscountCodeApprovedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"discount_code.approved","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"membership_id":"mem_7b1a1d043ee66d23f0967b28","discount_code":"JANE15","link":"https://example-coffee.com/discount/JANE15"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"discount_code.rejected":{"post":{"operationId":"webhook_discount_code_rejected","summary":"Discount code rejected","description":"A brand rejected the discount code you requested.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"discount_code.rejected"},"data":{"$ref":"#/components/schemas/WebhookDiscountCodeRejectedData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"discount_code.rejected","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"business":{"id":"biz_30b71995a9ec2fcd10ca0275","name":"Example Coffee Co."},"membership_id":"mem_7b1a1d043ee66d23f0967b28","requested_discount_code":"JANE50"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}},"webhook.test":{"post":{"operationId":"webhook_webhook_test","summary":"Test event","description":"Sent only by \"Send test\" in the dashboard, to that endpoint only. Not retried.","tags":["Webhooks"],"security":[],"parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Event id (evt_…). Identical on every retry and resend."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed. Reject if more than 5 minutes off."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated `v1,<base64 HMAC-SHA256>` over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded secret after `whsec_`. Two signatures during a 24h secret rotation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEventEnvelope"},{"type":"object","properties":{"type":{"const":"webhook.test"},"data":{"$ref":"#/components/schemas/WebhookWebhookTestData"}}}]},"example":{"id":"evt_2b8f0c6e1d4a9b7c3e5f1a2d","type":"webhook.test","timestamp":"2026-10-23T11:00:00Z","api_version":"2026-10-23","data":{"message":"This is a test event from Oshi.","endpoint_id":"we_4c1d9e0f2a3b5c6d7e8f9a0b"}}}}},"responses":{"2XX":{"description":"Return any 2xx within 10 seconds to acknowledge. Anything else (including redirects and timeouts) is retried after 1m, 5m, 30m, 2h, 5h, 10h and 10h."}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in the format `sk_live_{lookupId}_{secret}`.\nCreate API keys in your dashboard at /developers.\n"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message","example":"Invalid API key"}}},"KeyTestResponse":{"type":"object","required":["success","message","key"],"properties":{"success":{"type":"boolean","description":"Whether the API key is valid","example":true},"message":{"type":"string","description":"Human-readable status message","example":"API key is valid"},"key":{"type":"object","required":["id","name","affiliateId","readOnly"],"properties":{"id":{"type":"integer","description":"Unique identifier for this API key","example":42},"name":{"type":"string","description":"Name you assigned to this API key","example":"My Production Key"},"affiliateId":{"type":"string","description":"Your affiliate account ID","example":"123456"},"readOnly":{"type":"boolean","description":"Whether this key has read-only permissions","example":true}}}}},"Business":{"type":"object","description":"An affiliated business with rewards and referral information","properties":{"slug":{"type":["string","null"],"description":"URL-friendly identifier for the business","example":"amazon"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the business data was last updated","example":"2024-01-15T10:30:00.000Z"},"name":{"type":["string","null"],"description":"Business display name","example":"Amazon"},"shortDescription":{"type":["string","null"],"description":"Brief description of the business","example":"Shop millions of products"},"logoUrl":{"type":["string","null"],"format":"uri","description":"URL to the business logo image","example":"https://example.com/logo.png"},"transparentLogoUrl":{"type":["string","null"],"format":"uri","description":"Transparent PNG logo for overlays","example":"https://example.com/logo-transparent.png"},"coverUrl":{"type":["string","null"],"format":"uri","description":"URL to the business cover/banner image","example":"https://example.com/cover.jpg"},"coverDominantColor":{"type":["string","null"],"description":"Dominant color of the cover image (hex code)","example":"#232F3E"},"affiliateOverlayLogoUrl":{"type":["string","null"],"format":"uri","description":"Custom logo for affiliate overlay (if configured)"},"squareImageUrl":{"type":["string","null"],"format":"uri","description":"Square image for cards/thumbnails"},"squareImageDominantColor":{"type":["string","null"],"description":"Dominant color of the square image (hex code)"},"visibleCategories":{"type":"array","items":{"type":"string"},"description":"Product categories the business displays","example":["Electronics","Home & Garden"]},"website":{"type":["string","null"],"format":"uri","description":"Business website URL","example":"https://amazon.com"},"isOnline":{"type":["boolean","null"],"description":"Whether this is an online-only business","example":true},"isFeatured":{"type":"boolean","description":"Whether this business is featured on the main app","example":false},"rewards":{"$ref":"#/components/schemas/Rewards"},"rewardsSummary":{"$ref":"#/components/schemas/RewardsSummary","description":"Detailed rewards overview including social rewards, BTC pay bonus,\nand redemption details. Matches the public API format.\n"},"rewardsConfig":{"$ref":"#/components/schemas/PublicRewardsConfig","description":"Full rewards configuration including VIP tiers, referral settings,\nsocial rewards, and commission details.\n"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Visible products from this business"},"productCount":{"type":"integer","description":"Number of visible products","example":25},"categories":{"type":"array","items":{"type":"string"},"description":"Active product categories (intersection of visible categories and actual products)","example":["Electronics","Fashion"]},"socialLinks":{"type":"array","items":{"$ref":"#/components/schemas/SocialLink"},"description":"Business social media links"},"whyShopHere":{"type":["string","null"],"description":"Marketing copy explaining why to shop at this business","example":"Largest online marketplace with fast Prime shipping"},"isCurrentlyOfferingRewards":{"type":"boolean","description":"Whether the business is currently offering Bitcoin rewards","example":true},"referralUrl":{"type":"string","format":"uri","description":"Pre-built referral URL with all tracking parameters.\nReady to use—just redirect users here.\n","example":"https://amazon.com?ref=ABC123&utm_source=oshi&utm_medium=referral&utm_campaign=ref_ABC123&ttl=7776000&policy=first"},"handoffUrl":{"type":"string","format":"uri","description":"URL to the branded interstitial page that shows reward details\nbefore redirecting to the merchant store. Uses oshi.link by default,\nor the merchant's custom domain if one is configured.\nFormat: https://oshi.link/{affiliateCode} or https://{customDomain}/{affiliateCode}\n","example":"https://oshi.link/ABC123"},"affiliateSignupUrl":{"type":["string","null"],"format":"uri","description":"URL to the merchant-specific affiliate signup page.\nShare this link to invite others to become affiliates for this business.\nFormat: https://oshi.link/a/{hashedBusinessId}\nNull if the business has no hashed ID configured.\n","example":"https://oshi.link/a/abc123def456"},"referralCode":{"type":"string","description":"Your unique referral code for this business","example":"ABC123"},"attributionPeriodDays":{"type":"integer","description":"Number of days the referral cookie lasts","example":90},"affiliateCode":{"type":"string","description":"Your affiliate code (same as referralCode)","example":"ABC123"},"affiliatePercentage":{"type":["number","null"],"description":"**Deprecated**: Use `affiliateRewards.referringReward` instead.\nYour commission percentage (if custom rate negotiated).\n","example":10},"affiliateRewards":{"$ref":"#/components/schemas/AffiliateRewards"},"affiliateSince":{"type":"string","format":"date-time","description":"When you became an affiliate for this business","example":"2024-01-01T00:00:00.000Z"}}},"Rewards":{"type":"object","description":"Reward information for building your UI.\nSupports both percentage-based and fixed dollar amount rewards.\nSee the Rewards Display Guide at /docs/guides/rewards-display for\nexamples of how to format these values for display.\n","properties":{"headlinePercent":{"type":"number","description":"Main percentage to display prominently.\nIncludes first-purchase bonus if applicable.\nWill be 0 if `isFixedReward` is true.\n","example":5},"headlineFixed":{"type":["number","null"],"description":"Fixed dollar amount for first purchase bonus.\nOnly present when `isFixedReward` is true.\nDisplay as \"$X back in Bitcoin\".\n","example":30},"isFixedReward":{"type":"boolean","description":"Whether this is a fixed dollar amount reward vs percentage.\nIf true, use `headlineFixed` for display.\nIf false, use `headlinePercent` for display.\n","example":false},"basePercent":{"type":"number","description":"Ongoing reward rate after first purchase","example":3},"maxPercent":{"type":"number","description":"Maximum possible reward with VIP tiers","example":8},"hasVipTiers":{"type":"boolean","description":"Whether VIP progression is available","example":true},"hasReferralBonus":{"type":"boolean","description":"Whether first purchase gets a bonus (percentage or fixed)","example":true},"minimumPurchase":{"type":["number","null"],"description":"Minimum purchase amount required for the reward.\nTypically used with fixed rewards.\nDisplay as \"On orders over $X+\".\n","example":100}}},"AffiliateRewards":{"type":"object","description":"Your affiliate-specific reward configuration for this business.\nThese values may differ from the business's default rates if you have\nnegotiated custom terms.\n\nWhen building your UI:\n- For customer rewards, use `referredReward` + `referredRewardType`\n- For your commission, use `referringReward` + `referringRewardType`\n- For ongoing commissions, use `lifetimeCommission` + `lifetimeCommissionType`\n","properties":{"referringReward":{"type":["number","null"],"description":"Your commission amount when a customer you refer makes a purchase.\nInterpret based on `referringRewardType`.\n","example":10},"referringRewardType":{"type":"string","enum":["percentage","fixed"],"description":"Type of your referral commission.\n- `percentage`: referringReward is a percentage of the sale\n- `fixed`: referringReward is a fixed dollar amount\n","example":"percentage"},"referredReward":{"type":["number","null"],"description":"Reward amount for customers you refer (first purchase bonus).\nInterpret based on `referredRewardType`.\n","example":15},"referredRewardType":{"type":"string","enum":["percentage","fixed"],"description":"Type of reward for referred customers.\n- `percentage`: Display as \"X% back in Bitcoin\"\n- `fixed`: Display as \"$X back in Bitcoin\"\n","example":"percentage"},"minimumPurchase":{"type":["number","null"],"description":"Minimum purchase amount required for the referred customer reward.\nDisplay as \"On orders over $X+\" when present.\n","example":100},"lifetimeCommission":{"type":["number","null"],"description":"Your ongoing commission on all future purchases from referred customers.\nInterpret based on `lifetimeCommissionType`.\n","example":5},"lifetimeCommissionType":{"type":"string","enum":["percentage","fixed"],"description":"Type of lifetime commission.\n- `percentage`: lifetimeCommission is a percentage of each sale\n- `fixed`: lifetimeCommission is a fixed dollar amount per sale\n","example":"percentage"}}},"Product":{"type":"object","description":"A product from an affiliated business","properties":{"id":{"type":"string","description":"Internal product ID","example":"prod_123"},"productId":{"type":["string","null"],"description":"External product ID from the merchant","example":"ext_456"},"productType":{"type":["string","null"],"description":"Product category","example":"Electronics"},"title":{"type":"string","description":"Product display name","example":"Echo Dot (5th Gen)"},"image":{"type":["string","null"],"format":"uri","description":"Product image URL","example":"https://example.com/product.jpg"},"price":{"type":["number","null"],"description":"Product price","example":49.99},"handle":{"type":["string","null"],"description":"Product handle for URL construction (e.g., Shopify handle)","example":"echo-dot-5th-gen"},"collections":{"type":"array","items":{"type":"string"},"description":"Collections/categories this product belongs to","example":["Best Sellers","New Arrivals"]},"isFeatured":{"type":"boolean","description":"Whether this product is featured","example":false}}},"PublicBusinessListResponse":{"type":"object","description":"Paginated list of businesses","required":["businesses","pagination"],"properties":{"businesses":{"type":"array","items":{"$ref":"#/components/schemas/PublicBusinessSummary"}},"pagination":{"type":"object","required":["total","limit","offset","hasMore"],"properties":{"total":{"type":"integer","description":"Total number of businesses","example":150},"limit":{"type":"integer","description":"Page size","example":100},"offset":{"type":"integer","description":"Current offset","example":0},"hasMore":{"type":"boolean","description":"Whether more results are available","example":true}}}}},"PublicBusinessSummary":{"type":"object","description":"Business summary for listing pages","properties":{"slug":{"type":"string","description":"URL-friendly identifier","example":"amazon"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"name":{"type":"string","description":"Business display name","example":"Amazon"},"shortDescription":{"type":["string","null"],"description":"Brief business description"},"logoUrl":{"type":["string","null"],"format":"uri","description":"Business logo URL"},"transparentLogoUrl":{"type":["string","null"],"format":"uri","description":"Transparent PNG logo for overlays"},"affiliateOverlayLogoUrl":{"type":["string","null"],"format":"uri","description":"Custom overlay logo"},"coverUrl":{"type":["string","null"],"format":"uri","description":"Cover/banner image URL"},"squareImageUrl":{"type":["string","null"],"format":"uri","description":"Square thumbnail image"},"coverDominantColor":{"type":["string","null"],"description":"Dominant color of cover image (hex)","example":"#232F3E"},"squareImageDominantColor":{"type":["string","null"],"description":"Dominant color of square image (hex)"},"website":{"type":["string","null"],"format":"uri","description":"Business website URL"},"isOnline":{"type":["boolean","null"],"description":"Whether this is an online-only business"},"isFeatured":{"type":"boolean","description":"Whether this business is featured"},"referralCode":{"type":["string","null"],"description":"Oshi's referral tracking code for this business"},"attributionPeriodDays":{"type":["integer","null"],"description":"Cookie attribution period in days","example":90},"referralUrl":{"type":["string","null"],"format":"uri","description":"Pre-built referral URL with tracking parameters.\nPoints to the merchant with Oshi's affiliate tracking.\n","example":"https://amazon.com?ref=ABC123&utm_source=oshi&utm_medium=referral&utm_campaign=ref_ABC123&ttl=7776000&policy=first"},"handoffUrl":{"type":["string","null"],"format":"uri","description":"Consumer-facing rewards page URL. Uses merchant's custom domain if available,\notherwise defaults to oshi.link. Format: https://oshi.link/{code} or https://{custom_domain}/{code}\n","example":"https://oshi.link/ABC123"},"affiliateSignupUrl":{"type":["string","null"],"format":"uri","description":"URL to the merchant-specific affiliate signup page.\nFormat: https://oshi.link/a/{hashedBusinessId}\n","example":"https://oshi.link/a/abc123def456"},"rewardsSummary":{"$ref":"#/components/schemas/RewardsSummary"},"productCount":{"type":"integer","description":"Number of visible products"}}},"PublicBusinessDetail":{"type":"object","description":"Full business details for detail pages","allOf":[{"$ref":"#/components/schemas/PublicBusinessSummary"},{"type":"object","properties":{"attributionPeriodDays":{"type":"integer","description":"Cookie attribution period in days","example":90},"rewardsConfig":{"$ref":"#/components/schemas/PublicRewardsConfig"},"products":{"type":"array","items":{"$ref":"#/components/schemas/PublicProduct"}},"visibleCategories":{"type":"array","items":{"type":"string"},"description":"Product categories to display"},"whyShopHere":{"type":["string","null"],"description":"SEO marketing copy"},"socialLinks":{"type":"array","items":{"$ref":"#/components/schemas/SocialLink"}}}}]},"RewardsSummary":{"type":"object","description":"Detailed rewards overview","properties":{"basePercentage":{"type":["number","null"],"description":"Base reward percentage","example":3},"maxPercentage":{"type":["number","null"],"description":"Maximum reward with VIP tiers","example":8},"hasVipTiers":{"type":"boolean","description":"Whether VIP progression is available"},"isFixedReward":{"type":"boolean","description":"Whether this is a fixed dollar amount vs percentage"},"headlineFixed":{"type":["number","null"],"description":"Fixed dollar amount for first purchase bonus (null if percentage-based)"},"minimumPurchase":{"type":["number","null"],"description":"Minimum purchase amount required for the reward"},"referralBonus":{"type":["number","null"],"description":"Percentage referral bonus for first purchase (null if fixed or none)"},"socialRewardsEnabled":{"type":"boolean","description":"Whether social engagement rewards are active"},"socialRewardsTotalSats":{"type":"integer","description":"Total sats available from all social actions"},"btcPayBonusEnabled":{"type":"boolean","description":"Whether BTC payment bonus is active"},"btcPayBonus":{"type":["number","null"],"description":"Extra percentage for Bitcoin payments"},"hasRedemptionOffers":{"type":"boolean","description":"Whether loyalty redemption offers are available"},"redemptionMaxMultiplier":{"type":["number","null"],"description":"Maximum value multiplier for redemption offers"},"wineClubBonusEnabled":{"type":"boolean","description":"Whether a wine club member bonus is active (Vinoshipper integration)"},"wineClubBonusPercentage":{"type":["number","null"],"description":"Extra percentage back for wine club members (e.g., 10 = +10%)"}}},"PublicRewardsConfig":{"type":"object","description":"Full rewards configuration","properties":{"baseRewards":{"type":"object","properties":{"enabled":{"type":"boolean"},"minPercentage":{"type":["number","null"],"description":"Base reward percentage (before VIP tiers)"},"maxPercentage":{"type":["number","null"],"description":"Maximum reward percentage (with highest VIP tier)"},"hasVipTiers":{"type":"boolean","description":"Whether VIP tier progression is available"},"tiers":{"type":"array","description":"VIP tier definitions (empty if hasVipTiers is false)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Tier display name (e.g., \"Gold\", \"Platinum\")"},"discountPercentage":{"type":["number","null"],"description":"Reward percentage for this tier"},"currencyThreshold":{"type":["number","null"],"description":"Spending threshold to reach this tier (in merchant currency)"}}}}}},"btcPayBonus":{"type":"object","description":"Extra rewards for Bitcoin/Lightning payments","properties":{"enabled":{"type":"boolean","description":"Whether BTC payment bonus is active"},"bonus":{"type":["number","null"],"description":"Extra percentage for Bitcoin payments"}}},"referrals":{"type":"object","description":"Referral program configuration","properties":{"enabled":{"type":"boolean","description":"Whether referral rewards are active"},"referralBonus":{"type":["number","null"],"description":"Bonus for the referring user"},"referredReward":{"type":["number","null"],"description":"Reward for the referred user (first purchase bonus)"},"referringRewardType":{"type":["string","null"],"enum":["percentage","fixed"],"description":"Type of reward for the referring user.\n- `percentage`: Percentage of the sale\n- `fixed`: Fixed dollar amount\n"},"referredRewardType":{"type":["string","null"],"enum":["percentage","fixed"],"description":"Type of reward for the referred user.\n- `percentage`: Display as \"X% back\"\n- `fixed`: Display as \"$X back\"\n"},"minimumPurchase":{"type":["number","null"],"description":"Minimum purchase amount required for the referral reward.\nDisplay as \"On orders over $X+\" when present.\n"},"attributionPeriodDays":{"type":["integer","null"],"description":"Number of days the referral attribution lasts"}}},"lifetimeCommissions":{"type":"object","description":"Lifetime commission configuration for affiliates","properties":{"enabled":{"type":"boolean"},"percentage":{"type":["number","null"],"description":"Lifetime commission percentage"}}},"socialRewards":{"type":"object","description":"Social engagement rewards (follow, share, etc.)","properties":{"enabled":{"type":"boolean","description":"Whether social rewards are active"},"totalSats":{"type":"integer","description":"Total sats available from all social actions"},"rewards":{"type":"array","description":"Individual social platform rewards","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique reward ID"},"socialNetworkId":{"type":"string","description":"Platform identifier"},"platformName":{"type":"string","description":"Human-readable platform name (e.g., \"Instagram\", \"Twitter\")"},"platformIcon":{"type":["string","null"],"description":"Icon identifier for the platform"},"satsBonus":{"type":"integer","description":"Sats earned for this social action"},"active":{"type":["boolean","null"],"description":"Whether this specific reward is active"}}}}}},"redemption":{"type":"object","properties":{"hasOffers":{"type":"boolean"},"maxMultiplier":{"type":["number","null"],"description":"Maximum value multiplier for offers"}}}}},"PublicProduct":{"type":"object","description":"Product from a business","properties":{"id":{"type":"string"},"productId":{"type":"string"},"title":{"type":"string"},"image":{"type":["string","null"],"format":"uri"},"price":{"type":["number","null"]},"handle":{"type":["string","null"],"description":"Product handle for URL construction"},"productType":{"type":["string","null"],"description":"Product category"},"isFeatured":{"type":"boolean","description":"Whether this product is featured"}}},"SocialLink":{"type":"object","description":"Business social media link","properties":{"platform":{"type":"string","description":"Platform name (e.g., Instagram, Twitter)","example":"Instagram"},"url":{"type":"string","format":"uri","description":"Full URL to social profile","example":"https://instagram.com/amazon"}}},"WebhookBusiness":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","pattern":"^biz_[0-9a-f]{24}$","description":"Opaque brand id, stable per affiliate. Not an Oshi database id."},"name":{"type":"string"}}},"WebhookOrder":{"type":"object","description":"Platform order. Totals are decimal strings in the order currency.","required":["id"],"properties":{"id":{"type":"string","description":"Platform order id"},"number":{"type":["string","null"],"description":"Display number, e.g. \"#1001\""},"subtotal":{"type":["string","null"],"description":"Decimal string"},"currency":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"}}},"WebhookCustomerRef":{"type":["string","null"],"pattern":"^cus_[0-9a-f]{24}$","description":"Opaque customer identifier, stable per affiliate. Never contains PII."},"WebhookCommission":{"type":"object","required":["id","status","source","amount_sats","commission_percentage","created_at"],"properties":{"id":{"type":"string","pattern":"^com_[0-9a-f]{24}$","description":"Opaque commission id, stable per affiliate. Not an Oshi database id."},"status":{"type":"string","enum":["pending","paid","available","reversed"]},"source":{"type":"string","enum":["lifetime","repeat_purchase","manual"]},"amount_sats":{"type":"integer"},"commission_percentage":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"available_at":{"type":["string","null"],"format":"date-time"}}},"WebhookReversal":{"type":"object","required":["id","amount_sats","partial","reason"],"properties":{"id":{"type":["string","null"],"pattern":"^rev_[0-9a-f]{24}$","description":"Opaque reversal id, stable per affiliate. Null for a fraud reversal with no clawback record."},"amount_sats":{"type":"integer"},"partial":{"type":"boolean"},"reason":{"type":"string","enum":["refund","cancel","manual","fraud"]}}},"WebhookWithdrawal":{"type":"object","required":["id","status","amount_sats","destination_type","destination_masked","created_at"],"properties":{"id":{"type":"string","pattern":"^wd_[0-9a-f]{24}$","description":"Opaque withdrawal id, stable per affiliate. Not an Oshi database id."},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"amount_sats":{"type":"integer"},"destination_type":{"type":"string","enum":["bolt11","lightning_address"]},"destination_masked":{"type":"string","description":"bolt11: first 12 chars + …; Lightning address: first char + ***@domain"},"origin":{"type":["string","null"],"enum":["affiliate_portal","rewards_app","auto",null]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"failure":{"type":["object","null"],"properties":{"code":{"type":["string","null"]},"message":{"type":"string"}}}}},"WebhookMembership":{"type":"object","required":["id","code"],"properties":{"id":{"type":"string","pattern":"^mem_[0-9a-f]{24}$","description":"Opaque program membership id, stable per affiliate. Not an Oshi database id."},"code":{"type":"string"},"link":{"type":["string","null"]},"discount_code":{"type":["string","null"]},"is_oshi_network":{"type":"boolean"},"joined_via":{"type":"string","enum":["auto","approved","imported"]}}},"WebhookEventEnvelope":{"type":"object","required":["id","type","timestamp","api_version","data"],"description":"Body of every webhook request. Signed bytes are the exact compact JSON body.","properties":{"id":{"type":"string","pattern":"^evt_[0-9a-f]{24}$","description":"Event id; same as the webhook-id header. Dedupe on it."},"type":{"type":"string"},"timestamp":{"type":"string","format":"date-time","description":"When the event happened (UTC, seconds precision)."},"api_version":{"type":"string","example":"2026-10-23"},"data":{"type":"object"}}},"WebhookCommissionCreatedData":{"type":"object","required":["commission","business"],"properties":{"commission":{"$ref":"#/components/schemas/WebhookCommission"},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"order":{"oneOf":[{"$ref":"#/components/schemas/WebhookOrder"},{"type":"null"}]},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"}}},"WebhookCommissionPaidData":{"type":"object","required":["commission","business"],"properties":{"commission":{"$ref":"#/components/schemas/WebhookCommission"},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"order":{"oneOf":[{"$ref":"#/components/schemas/WebhookOrder"},{"type":"null"}]},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"}}},"WebhookCommissionAvailableData":{"type":"object","required":["commission","business"],"properties":{"commission":{"$ref":"#/components/schemas/WebhookCommission"},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"order":{"oneOf":[{"$ref":"#/components/schemas/WebhookOrder"},{"type":"null"}]},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"}}},"WebhookCommissionReversedData":{"type":"object","required":["commission","business","reversal"],"properties":{"commission":{"$ref":"#/components/schemas/WebhookCommission"},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"order":{"oneOf":[{"$ref":"#/components/schemas/WebhookOrder"},{"type":"null"}]},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"},"reversal":{"$ref":"#/components/schemas/WebhookReversal"}}},"WebhookReferralCreatedData":{"type":"object","properties":{"referral":{"type":"object","properties":{"id":{"type":"string","pattern":"^rfl_[0-9a-f]{24}$","description":"Opaque referral id, stable per affiliate. Not an Oshi database id."},"created_at":{"type":"string","format":"date-time"}}},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"}}},"WebhookReferralRewardPaidData":{"type":"object","properties":{"referral":{"type":"object","properties":{"id":{"type":"string","pattern":"^rfl_[0-9a-f]{24}$","description":"Opaque referral id, stable per affiliate. Not an Oshi database id."}}},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"amount_sats":{"type":"integer"},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"}}},"WebhookOrderAttributedData":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/WebhookOrder"},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"},"attribution":{"type":"string","enum":["first_purchase","repeat_purchase"]},"commission_sats":{"type":["integer","null"]}}},"WebhookOrderRefundedData":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/WebhookOrder"},"business":{"$ref":"#/components/schemas/WebhookBusiness"},"customer_ref":{"$ref":"#/components/schemas/WebhookCustomerRef"},"refund_type":{"type":"string","enum":["full","partial","cancelled"]}}},"WebhookWithdrawalCreatedData":{"type":"object","properties":{"withdrawal":{"$ref":"#/components/schemas/WebhookWithdrawal"}}},"WebhookWithdrawalCompletedData":{"type":"object","properties":{"withdrawal":{"$ref":"#/components/schemas/WebhookWithdrawal"}}},"WebhookWithdrawalFailedData":{"type":"object","properties":{"withdrawal":{"$ref":"#/components/schemas/WebhookWithdrawal"}}},"WebhookProgramJoinedData":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/WebhookBusiness"},"membership":{"$ref":"#/components/schemas/WebhookMembership"}}},"WebhookProgramApplicationDeniedData":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/WebhookBusiness"},"application":{"type":"object","properties":{"id":{"type":"string","pattern":"^app_[0-9a-f]{24}$","description":"Opaque application id, stable per affiliate. Not an Oshi database id."}}}}},"WebhookProgramRemovedData":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/WebhookBusiness"},"membership":{"type":"object","properties":{"id":{"type":"string","pattern":"^mem_[0-9a-f]{24}$","description":"Opaque program membership id, stable per affiliate. Not an Oshi database id."},"code":{"type":"string"}}}}},"WebhookDiscountCodeApprovedData":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/WebhookBusiness"},"membership_id":{"type":"string","pattern":"^mem_[0-9a-f]{24}$","description":"Opaque program membership id, stable per affiliate. Not an Oshi database id."},"discount_code":{"type":"string"},"link":{"type":["string","null"]}}},"WebhookDiscountCodeRejectedData":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/WebhookBusiness"},"membership_id":{"type":"string","pattern":"^mem_[0-9a-f]{24}$","description":"Opaque program membership id, stable per affiliate. Not an Oshi database id."},"requested_discount_code":{"type":"string"}}},"WebhookWebhookTestData":{"type":"object","properties":{"message":{"type":"string"},"endpoint_id":{"type":"string","pattern":"^we_[0-9a-f]{24}$"}}}}},"security":[{"BearerAuth":[]}]}