openapi: 3.0.1 info: title: PromoCodeVerified API description: | Real-time access to verified promo codes and store audit data. Perfect for AI agents, browser extensions, and e-commerce applications. **Creative Commons Attribution-NonCommercial-ShareAlike 4.0**: You may freely use this API for non-commercial purposes with attribution. See https://promocodeverified.com/terms for complete terms and attribution requirements. version: '1.0' contact: email: contact@promocodeverified.com license: name: CC BY-NC-SA 4.0 url: https://creativecommons.org/licenses/by-nc-sa/4.0/ servers: - url: https://promocodeverified.com description: Production server paths: /api/stores: get: operationId: searchStores summary: List all verified stores with pagination and search description: | Get a paginated list of all verified stores. Use search parameters to find specific stores. **Use Cases:** - Build store directories - Find API endpoints for specific retailers - Category-based filtering for targeted coupon searches parameters: - in: query name: q schema: type: string description: Search by store name or domain (e.g., "Nike", "amazon.com") example: "Nike" - in: query name: category schema: type: string enum: ["Fashion", "Electronics", "Health", "Home", "Beauty", "Software", "Food", "Sports"] description: Filter by store category example: "Fashion" - in: query name: page schema: type: integer minimum: 1 default: 1 description: Page number for pagination - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 25 description: Number of stores per page responses: "200": description: Successful response with store list content: application/json: schema: type: object properties: meta: type: object properties: total: type: integer description: Total number of stores matching the query example: 191 page: type: integer description: Current page number example: 1 limit: type: integer description: Number of items per page example: 25 has_more: type: boolean description: Whether there are more pages available example: true documentation: type: string description: Usage guidance stores: type: array items: type: object properties: name: type: string description: Store name example: "Nike" category: type: string description: Store category example: "Fashion" updated_at: type: string format: date-time description: Last update timestamp example: "2024-01-01T22:24:10.659Z" api_url: type: string format: uri description: Direct API endpoint for this store's coupon data example: "https://promocodeverified.com/api/store/nike" web_url: type: string format: uri description: Human-readable store page example: "https://promocodeverified.com/store/nike" example: meta: total: 191 page: 1 limit: 25 has_more: true documentation: "Access individual store details via the api_url field." stores: - name: "Nike" category: "Fashion" updated_at: "2024-01-01T22:24:10.659Z" api_url: "https://promocodeverified.com/api/store/nike" web_url: "https://promocodeverified.com/store/nike" /api/store/{slug}: get: operationId: getStoreDeals summary: Get detailed coupon data and verification info for a store description: | Returns comprehensive coupon data, usage instructions, FAQs, and verification proof for a specific store. **What you'll get:** - Active promo codes and automatic deals - Usage tips and restrictions - Frequently asked questions - Verification timestamps and methods - Success rate statistics parameters: - in: path name: slug schema: type: string required: true description: Store identifier slug (usually the domain with hyphens) example: "nike" responses: "200": description: Successful response with complete store coupon data content: application/json: schema: type: object properties: title: type: string description: SEO-optimized title with coupon info example: "Nike Promo Code SAVE: 15% Off Running Shoes" name: type: string description: Store name example: "Nike" description: type: string description: Store description and coupon details category: type: string description: Store category example: "Fashion" website: type: string format: uri description: Store website URL example: "https://www.nike.com" logo: type: string format: uri description: Store logo URL verified_at: type: string format: date-time description: Last verification timestamp deal_url: type: string format: uri description: Direct link with affiliate tracking source_url: type: string format: uri description: PromoCodeVerified store page active_offers: type: array description: Currently active coupons and deals items: type: object properties: type: type: string enum: ["coupon", "deal"] description: Type of offer code: type: string nullable: true description: Promo code to enter (null for automatic deals) example: "SAVE15" title: type: string description: Offer description example: "15% off running shoes" expires_at: type: string format: date-time nullable: true description: Expiration date (null if no expiration) url: type: string format: uri description: Direct offer link verified: type: boolean description: Whether this offer was manually verified knowledge: type: object description: Usage instructions and verification proof properties: usage_tips: type: array items: type: string description: Tips for using the coupons example: ["Applies to all items", "Cannot combine with other offers"] faqs: type: array items: type: object properties: question: type: string example: "How do I apply the SAVE15 code?" answer: type: string example: "Enter SAVE15 at checkout for 15% off your entire order." verification: type: object description: Proof of coupon testing properties: last_tested: type: string format: date-time description: When the coupon was last verified method: type: string description: How the verification was performed example: "Verified via checkout simulation: 1 items - Total $99.99" tester: type: string description: Who performed the verification example: "PCV Editorial" stats: type: object description: Success rate and offer statistics properties: total_offers: type: integer description: Number of active offers example: 1 success_rate: type: string description: Historical success rate example: "100%" example: title: "Nike Promo Code SAVE: 15% Off Running Shoes" name: "Nike" description: "Get 15% off running shoes with code SAVE, plus free shipping on orders over $100. Limited time offer." category: "Fashion" website: "https://www.nike.com" verified_at: "2024-01-01T22:24:10.659Z" active_offers: - type: "coupon" code: "SAVE" title: "15% off running shoes" verified: true knowledge: usage_tips: ["Valid on running shoes only", "Cannot combine with other offers"] faqs: - question: "How do I apply the SAVE code?" answer: "Enter SAVE at checkout for 15% off running shoes." verification: last_tested: "2024-01-01T21:08:46.628Z" method: "Verified via checkout simulation" tester: "PCV Editorial" stats: total_offers: 1 success_rate: "100%" "404": description: Store not found content: application/json: schema: type: object properties: error: type: string example: "Store not found"