{"openapi":"3.0.3","info":{"title":"CashbackHive Publisher API","version":"1.0.0","description":"The CashbackHive Publisher API lets you retrieve brand data and generate reports for clicks, transactions, and commissions.\n\nAll endpoints require authentication via the `x-publisher-key` header (Demand API routes also accept `AccessKey`).","contact":{"name":"CashbackHive","url":"https://cashbackhive.com"}},"servers":[{"url":"https://api.cashbackhive.com"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-publisher-key","description":"Your publisher API key (e.g. `cbh_ak_a1b2c3d4...`). Generate one from the Publisher Portal under **Developer → API Keys**."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message."}},"required":["error"]},"Brand":{"type":"object","properties":{"id":{"type":"string","description":"Unique brand identifier (slug).","example":"example-store"},"name":{"type":"string","description":"Brand display name.","example":"Example Store"},"domain":{"type":"string","nullable":true,"description":"Brand's website domain.","example":"example-store.com"},"category":{"type":"string","description":"Brand category.","example":"Retail"},"geo":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 country code the brand operates in (e.g. US, GB). `null` for global brands.","example":"US"},"description":{"type":"string","nullable":true,"description":"Short description of the brand. `null` when not available.","example":"Example Store sells quality goods at great prices."},"logo_url":{"type":"string","nullable":true,"description":"URL of the brand's logo image. `null` when not available.","example":"https://cdn.sanity.io/images/project/dataset/example-logo.png"},"payout":{"type":"string","description":"Your payout rate for this brand, after your commission share (split) has been applied. Returns `\"Varies\"` when no rate can be resolved.","example":"5%"},"tracking_url":{"type":"string","description":"Tracking URL with your publisher ID embedded. When `supports_deeplinking` is `true`, append `&url=<URL-encoded product page>` to deep-link to a specific page on the merchant's site. The destination must be on the brand's own domain — otherwise it's ignored and the shopper lands on the homepage.","example":"https://sales.cashbackhive.com/go/example-store?publisherId=pub_a1b2c3d4"},"supports_deeplinking":{"type":"boolean","description":"Whether you can deep-link to specific pages for this brand by appending a `url` param to `tracking_url`.","example":true}},"required":["id","name","domain","category","geo","description","logo_url","payout","tracking_url","supports_deeplinking"]},"BrandsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}},"page":{"type":"integer","description":"Current page number.","example":1},"total":{"type":"integer","description":"Total number of brands matching the query.","example":42}},"required":["data","page","total"]},"ReportRequest":{"type":"object","properties":{"start_date":{"type":"string","format":"date","description":"Start date for the report period (YYYY-MM-DD).","example":"2026-01-01"},"end_date":{"type":"string","format":"date","description":"End date for the report period (YYYY-MM-DD).","example":"2026-01-31"},"type":{"type":"string","enum":["clicks","transactions","commissions"],"description":"Report type. `\"clicks\"` is currently unavailable and returns a 400.","example":"transactions"},"format":{"type":"string","enum":["json","csv"],"default":"json","description":"Response format. Defaults to `\"json\"`.","example":"json"}},"required":["start_date","end_date","type"]},"ClickRow":{"type":"object","properties":{"date":{"type":"string","description":"Click timestamp (ISO 8601)."},"brand":{"type":"string","description":"Store / brand name."},"store_slug":{"type":"string","description":"Store slug."},"click_id":{"type":"string","description":"Internal click ID."},"publisher_click_id":{"type":"string","nullable":true,"description":"Your click ID (if provided)."},"ip_address":{"type":"string","nullable":true,"description":"Visitor IP address."},"referrer":{"type":"string","nullable":true,"description":"HTTP referrer."}}},"TransactionRow":{"type":"object","properties":{"transaction_id":{"type":"string","description":"Unique transaction identifier. Stable across requests — use this as a dedup key.","example":"txn_001abc"},"date":{"type":"string","description":"Transaction event date."},"brand":{"type":"string","description":"Merchant / brand name."},"amount":{"type":"number","description":"Sale amount.","example":49.99},"commission":{"type":"number","description":"Commission you earned, after your commission share (split) has been applied.","example":2.5},"status":{"type":"string","enum":["pending","approved","cancelled","unknown"],"description":"Transaction status.","example":"pending"},"order_number":{"type":"string","nullable":true,"description":"Merchant order reference."},"currency":{"type":"string","description":"ISO 4217 currency code.","example":"USD"},"publisher_click_id":{"type":"string","nullable":true,"description":"Your click ID associated with the transaction, if provided at click time."}}},"CommissionRow":{"type":"object","properties":{"date":{"type":"string","description":"Transaction event date."},"brand":{"type":"string","description":"Merchant / brand name."},"amount":{"type":"number","description":"Sale amount.","example":49.99},"commission":{"type":"number","description":"Commission you earned, after your commission share (split) has been applied.","example":2.5},"status":{"type":"string","enum":["pending","approved","cancelled","unknown"],"description":"Transaction status.","example":"pending"},"currency":{"type":"string","description":"ISO 4217 currency code.","example":"USD"}}},"ReportResponse":{"type":"object","properties":{"report_id":{"type":"string","description":"Unique report identifier.","example":"rpt_001abc"},"type":{"type":"string","enum":["clicks","transactions","commissions"],"description":"Report type."},"start_date":{"type":"string","format":"date","description":"Report start date."},"end_date":{"type":"string","format":"date","description":"Report end date."},"total_records":{"type":"integer","description":"Number of records in the report.","example":128},"data":{"type":"array","description":"Report rows. Shape varies by report type.","items":{"oneOf":[{"$ref":"#/components/schemas/ClickRow"},{"$ref":"#/components/schemas/TransactionRow"},{"$ref":"#/components/schemas/CommissionRow"}]}}},"required":["report_id","type","start_date","end_date","total_records","data"]},"DemandBrandItem":{"type":"object","properties":{"merchant_id":{"type":"integer","description":"Brand ID.","example":123},"name":{"type":"string","description":"Brand display name. Falls back to the domain when no name is set.","example":"Example Store"},"campaign_id":{"type":"integer","nullable":true,"description":"Preferred campaign ID (homepage, else deeplink)."},"domain":{"type":"string","nullable":true,"example":"example-store.com"},"click_url_homepage":{"type":"string","description":"Encrypted homepage tracking URL."},"click_url_deeplink":{"type":"string","description":"Encrypted deeplink tracking URL."},"country_code":{"type":"string","nullable":true,"example":"US"},"geo":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 country code for this brand row (campaign country, else brand default).","example":"US"},"logo_url":{"type":"string","nullable":true,"description":"Stable, publicly reachable brand logo URL. Safe to store and hotlink.","example":"https://d2hsyurrcewa92.cloudfront.net/brands/example-store/3f1c9a2e-7b4d-4c8e-9a1f-2d6b8e4c0a71.png"},"banner_image":{"type":"string","nullable":true,"description":"Stable, publicly reachable banner / hero image URL. Safe to store and hotlink.","example":"https://d2hsyurrcewa92.cloudfront.net/brands/example-store/8c2d4e6f-1a3b-4c5d-8e7f-9a0b1c2d3e4f.jpg"},"restricated_traffic":{"type":"array","items":{"type":"string"},"description":"Restricted traffic type names."},"new_deal":{"type":"integer","enum":[0,1],"example":0},"last_updated_date":{"type":"string","nullable":true,"description":"YYYY-MM-DD","example":"2026-03-01"},"commission_rate":{"type":"string","nullable":true,"description":"Your payout rate for the brand, after your commission share (split) has been applied. Null when no rate can be resolved."}},"required":["merchant_id","name","campaign_id","domain","country_code","geo","logo_url","banner_image","restricated_traffic","new_deal","last_updated_date"]},"DemandBrandsListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/DemandBrandItem"}},"page":{"type":"integer","description":"Current page number.","example":2},"limit":{"type":"integer","description":"Page size.","example":25},"total":{"type":"integer","description":"Total matching brands across all pages.","example":251}},"required":["success","data","page","limit","total"]},"ValidationErrors":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"end_date":["The date range should not be more than 30 days."]}}},"required":["errors"]},"RevenueShareDaywiseRow":{"type":"object","properties":{"publisher_revenue":{"type":"string","nullable":true,"example":"12.5000"},"gross_revenue":{"type":"string","nullable":true,"description":"Omitted for CPC publishers (revenueType = 2).","example":"18.0000"},"date":{"type":"string","format":"date","nullable":true,"example":"2026-08-01"},"click_count":{"type":"integer","example":42}},"required":["publisher_revenue","date","click_count"]},"RevenueShareSourceLevelRow":{"type":"object","properties":{"publisher_revenue":{"type":"string","nullable":true,"example":"12.5000"},"gross_revenue":{"type":"string","nullable":true,"description":"Omitted for CPC publishers (revenueType = 2).","example":"18.0000"},"source_id":{"type":"string","nullable":true,"example":"sub_abc"},"click_count":{"type":"integer","example":42}},"required":["publisher_revenue","source_id","click_count"]},"RevenueShareClickIdRow":{"type":"object","properties":{"transaction_id":{"type":"string","nullable":true,"example":"txn_001abc"},"click_id":{"type":"string","nullable":true},"publisher_revenue":{"type":"string","nullable":true,"example":"2.5000"},"gross_revenue":{"type":"string","nullable":true,"description":"Omitted for CPC publishers (revenueType = 2).","example":"3.6000"},"sales_amount":{"type":"string","nullable":true,"description":"Order sale amount.","example":"49.9900"},"status":{"type":"string","nullable":true,"enum":["pending","approved","cancelled","unknown"],"description":"Transaction status (lowercase).","example":"pending"},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency code.","example":"USD"},"user_id":{"type":"string","nullable":true},"date":{"type":"string","format":"date","nullable":true,"example":"2026-08-01"},"brand_name":{"type":"string","nullable":true,"example":"example-store.com"},"source_id":{"type":"string","nullable":true},"sub_id":{"type":"string","nullable":true},"offer_id":{"type":"string","nullable":true,"description":"MD5 of brand_id."}},"required":["transaction_id","click_id","publisher_revenue","user_id","date","brand_name","source_id"]},"RevenueShareResponse":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/RevenueShareDaywiseRow"},{"$ref":"#/components/schemas/RevenueShareSourceLevelRow"},{"$ref":"#/components/schemas/RevenueShareClickIdRow"}]}},"page":{"type":"integer","description":"Current page number.","example":2},"limit":{"type":"integer","description":"Page size.","example":25},"total":{"type":"integer","description":"Total matching rows across all pages.","example":251}},"required":["data","page","limit","total"]}}},"paths":{"/v1/brands":{"get":{"tags":["Brands"],"summary":"List available brands","description":"Sanity catalog only. Retrieve a paginated list of brands in your network along with their payout details and tracking links. Brands where `supports_deeplinking` is `true` let you deep-link to a specific page by appending a `url` param to `tracking_url`.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number for pagination. Defaults to 1."},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Number of brands per page (max 100). Defaults to 25."},{"name":"search","in":"query","schema":{"type":"string"},"description":"Filter brands by name."}],"responses":{"200":{"description":"A paginated list of brands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandsResponse"},"example":{"data":[{"id":"example-store","name":"Example Store","domain":"example-store.com","category":"Retail","geo":"US","description":"Example Store sells quality goods at great prices.","logo_url":"https://cdn.sanity.io/images/project/dataset/example-logo.png","payout":"5%","tracking_url":"https://sales.cashbackhive.com/go/example-store?publisherId=pub_a1b2c3d4","supports_deeplinking":true}],"page":1,"total":42}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Unauthorized"}}}}}}},"/v1/report":{"post":{"tags":["Reports"],"summary":"Generate a report","description":"Sanity catalog only. Generate a report of transactions or commissions for a given date range. Supports JSON and CSV output formats.\n\nThe `clicks` report type is currently unavailable on this endpoint and returns a 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"},"example":{"start_date":"2026-01-01","end_date":"2026-01-31","type":"transactions","format":"json"}}}},"responses":{"200":{"description":"Report generated successfully. Returns JSON by default, or a CSV file when `format` is `\"csv\"`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"},"example":{"report_id":"rpt_001abc","type":"transactions","start_date":"2026-01-01","end_date":"2026-01-31","total_records":128,"data":[{"transaction_id":"txn_001abc","date":"2026-01-05","brand":"Example Store","amount":49.99,"commission":2.5,"status":"approved","order_number":"ORD-12345","currency":"USD","publisher_click_id":"pub-click-123"}]}},"text/csv":{"schema":{"type":"string"},"example":"transaction_id,date,brand,amount,commission,status,order_number,currency,publisher_click_id\ntxn_001abc,2026-01-05,Example Store,49.99,2.5,approved,ORD-12345,USD,pub-click-123"}}},"400":{"description":"Validation error — missing or invalid fields, or an unavailable report type (`clicks`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"start_date is required"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Unauthorized"}}}}}}}}}