{"openapi":"3.1.0","info":{"title":"CardDeals Public Deal API","version":"1.0.0","description":"Anonymous, read-only access to current U.S. gift-card discounts. CardDeals may earn a commission from third-party purchase links. Prices, availability, and seller terms can change; recheck before purchase.","contact":{"name":"CardDeals Support","url":"https://carddeals.co/contact","email":"support@carddeals.co"},"license":{"name":"CardDeals API Terms","url":"https://carddeals.co/terms"}},"servers":[{"url":"https://catalog.carddeals.co"}],"tags":[{"name":"Gift-card deals"}],"paths":{"/v1/deals/search":{"get":{"operationId":"searchGiftCardDeals","summary":"Search current gift-card deals","description":"Search by brand text or category. Results contain current provider links but do not execute a purchase.","tags":["Gift-card deals"],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Brand or merchant text."},{"name":"category","in":"query","schema":{"type":"string","maxLength":80},"description":"CardDeals category slug."},{"name":"min_discount","in":"query","schema":{"type":"number","minimum":0,"maximum":100,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"sort","in":"query","schema":{"type":"string","enum":["best_discount","name"],"default":"best_discount"}}],"responses":{"200":{"description":"Matching live deal products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/deals/lookup":{"get":{"operationId":"lookupGiftCardDeals","summary":"Look up multiple gift-card brands","tags":["Gift-card deals"],"parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated CardDeals product IDs or exact brand slugs; maximum 10.","schema":{"type":"string","maxLength":1200}}],"responses":{"200":{"description":"Resolved deal products and unknown IDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/deals/brands/{brand}":{"get":{"operationId":"getGiftCardDeals","summary":"Get current deals for one brand","tags":["Gift-card deals"],"parameters":[{"name":"brand","in":"path","required":true,"description":"Exact brand slug, CardDeals product ID, or exact brand name.","schema":{"type":"string","minLength":1,"maxLength":120}}],"responses":{"200":{"description":"The current product and provider deals, or a null product if unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"ProviderDeal":{"type":"object","required":["deal_id","provider_name","provider_slug","discount_percent","in_stock","fetched_at","purchase_url","variant","variant_label","coupon","conditions","seller_terms","relationship","disclosure"],"properties":{"deal_id":{"type":"string","example":"offer:starbucks:cardcash:online"},"provider_name":{"type":"string","example":"CardCash"},"provider_slug":{"type":"string","example":"cardcash"},"discount_percent":{"type":"number","minimum":0,"maximum":100},"in_stock":{"type":"boolean","enum":[true]},"fetched_at":{"type":["string","null"],"format":"date-time"},"purchase_url":{"type":"string","format":"uri"},"variant":{"type":["string","null"]},"variant_label":{"type":["string","null"]},"coupon":{"oneOf":[{"type":"object","required":["code","label","expiration"],"properties":{"code":{"type":"string"},"label":{"type":"string"},"expiration":{"type":"string"}}},{"type":"null"}]},"conditions":{"type":"array","items":{"type":"string"}},"seller_terms":{"type":"object","required":["reported_guarantee_days","note"],"properties":{"reported_guarantee_days":{"type":["integer","null"],"minimum":1},"note":{"type":"string"}}},"relationship":{"type":"string","enum":["affiliate","direct"]},"disclosure":{"type":"string"},"listings":{"type":"array","items":{"type":"object","required":["id","balance","price","discount_percent","currency","purchase_url"],"properties":{"id":{"type":"string"},"balance":{"type":"number","minimum":0},"price":{"type":"number","minimum":0},"discount_percent":{"type":"number","minimum":0,"maximum":100},"currency":{"type":"string","enum":["USD"]},"purchase_url":{"type":"string","format":"uri"}}}}}},"GiftCardDealProduct":{"type":"object","required":["product_id","name","slug","canonical_url","base_domain","category","best_discount_percent","carddeals_inventory_status","deals"],"properties":{"product_id":{"type":"string","example":"brand:starbucks"},"name":{"type":"string","example":"Starbucks"},"slug":{"type":"string","example":"starbucks"},"canonical_url":{"type":"string","format":"uri"},"base_domain":{"type":["string","null"]},"category":{"oneOf":[{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},{"type":"null"}]},"best_discount_percent":{"type":"number","minimum":0,"maximum":100},"carddeals_inventory_status":{"type":"string","enum":["included","unavailable"]},"deals":{"type":"array","items":{"$ref":"#/components/schemas/ProviderDeal"}}}},"SearchResponse":{"type":"object","required":["schema_version","as_of","currency","affiliate_disclosure","freshness_notice","query","total","products"],"properties":{"schema_version":{"type":"string","example":"1.0.0"},"as_of":{"type":"string","format":"date-time"},"currency":{"type":"string","enum":["USD"]},"affiliate_disclosure":{"type":"string","example":"CardDeals may earn a commission when a purchase is made through a third-party provider link."},"freshness_notice":{"type":"string","example":"Gift-card discounts, inventory, and seller terms can change. Recheck the destination before purchasing."},"query":{"type":"object","required":["text","category","min_discount_percent","limit","sort"],"properties":{"text":{"type":["string","null"]},"category":{"type":["string","null"]},"min_discount_percent":{"type":"number"},"limit":{"type":"integer"},"sort":{"type":"string","enum":["best_discount","name"]}}},"total":{"type":"integer","minimum":0},"products":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardDealProduct"}}}},"LookupResponse":{"type":"object","required":["schema_version","as_of","currency","affiliate_disclosure","freshness_notice","products","not_found"],"properties":{"schema_version":{"type":"string","example":"1.0.0"},"as_of":{"type":"string","format":"date-time"},"currency":{"type":"string","enum":["USD"]},"affiliate_disclosure":{"type":"string","example":"CardDeals may earn a commission when a purchase is made through a third-party provider link."},"freshness_notice":{"type":"string","example":"Gift-card discounts, inventory, and seller terms can change. Recheck the destination before purchasing."},"products":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardDealProduct"}},"not_found":{"type":"array","items":{"type":"string"}}}},"ProductResponse":{"type":"object","required":["schema_version","as_of","currency","affiliate_disclosure","freshness_notice","product"],"properties":{"schema_version":{"type":"string","example":"1.0.0"},"as_of":{"type":"string","format":"date-time"},"currency":{"type":"string","enum":["USD"]},"affiliate_disclosure":{"type":"string","example":"CardDeals may earn a commission when a purchase is made through a third-party provider link."},"freshness_notice":{"type":"string","example":"Gift-card discounts, inventory, and seller terms can change. Recheck the destination before purchasing."},"product":{"oneOf":[{"$ref":"#/components/schemas/GiftCardDealProduct"},{"type":"null"}]},"message":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Anonymous rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}