{"uid":"cap_iljzcxEUU0nm8FIK64C-v","slug":"tiresapi-com-6bb15125","name":"TiresAPI Retailer-Coverage Request Submission","description":"Submit a retailer-coverage request. If we already cover the (retailer, zip) combo the row is still logged for analytics AND the $0.01 is credited back to the agent's virtual balance — so agents aren't out of pocket for a useful-but-already-served signal.","url":"https://tiresapi.com/api/v1/requests/retailer-coverage","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000},"zip_code":{"type":"string","pattern":"^[0-9]{5}$"},"retailer_key":{"type":"string","maxLength":100,"description":"Uppercase scraper key."}}},"responseSchema":{"type":"json","example":{"status":"queued","request_id":4012,"credited_usd":null}},"example":{"request":{"notes":"QA test for retailer coverage tracking in Austin TX area","zip_code":"78701","retailer_key":"DISCOUNT_TIRE"},"response":{"notes":"Request queued for the data team to triage.","status":"queued","zip_code":"78701","amount_usd":"0.010","is_covered":false,"request_id":9,"credited_usd":"0.000000","request_type":"retailer_coverage","retailer_key":"DISCOUNT_TIRE","virtual_balance_usd_after":null}},"exampleRequest":{"notes":"QA test for retailer coverage tracking in Austin TX area","zip_code":"78701","retailer_key":"DISCOUNT_TIRE"},"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_YXi7f0rFXnSmKPN0sYPRO","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Submits a request to expand retailer coverage for a given retailer and ZIP code combination, logging it for analytics and crediting back $0.01 if the combo is already covered.","exampleAgentPrompt":"Submit a retailer-coverage request to TiresAPI for Discount Tire in ZIP code 78701 — I want to make sure that retailer-ZIP combo is being tracked even if it's already covered.","exampleUseCases":null,"resultDescription":"A confirmation that the retailer-ZIP coverage request was logged for analytics. If the combination was already covered, the $0.01 call cost is credited back to the agent's virtual balance. Returns the coverage status (new vs. already-served) and any relevant request ID or log entry.","failureModes":["Invalid or unrecognized retailer identifier — returns 400 with retailer validation error","Malformed or non-existent ZIP code — returns 400 with ZIP validation error","Insufficient virtual balance to cover the $0.01 fee — returns 402 payment required","Rate limiting or quota exceeded — returns 429","Service unavailable or timeout — returns 503"],"whenToPreferThis":"Use this endpoint when you want to signal to TiresAPI that a specific retailer-ZIP combination should be added to or confirmed in their coverage network. Ideal for agents that have encountered a coverage gap during inventory or price lookups and want to proactively request expansion. The built-in credit-back mechanism makes it safe to call even for already-covered combos, so agents can use it both as a coverage gap signal and as a coverage verification step without financial risk.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T00:35:52.374Z","isFirstParty":false}