Dollar General API - Store Prices, Stock, Deals, Coupons
Dollar General product data as structured JSON at the store you choose - search with that store's price and units on hand, product detail by UPC, a store locator that returns one product's unit count at up to 25 nearby stores in one call, on-sale and clearance listings, and the current digital coupons. 5 endpoints, 1 credit each.
Dollar General via Scavio
Search Dollar General and read products at the store you choose: that store's price, original price and units on hand, with digital coupons attached. One store-locator call returns a product's unit count at up to 25 nearby stores. List what is on sale or on clearance at a store, and page the current digital coupons. All endpoints return structured JSON.
When to trigger
Use this skill when the user asks to:
- Find household, grocery, health or beauty items at Dollar General by keyword
- Check what an item costs at a specific Dollar General store, and how many are on the shelf
- Find which Dollar General stores near a ZIP have a product in stock, and how many units each has
- List what is on sale or on clearance at a Dollar General store
- List Dollar General digital coupons, or the coupons that apply to a product
- Look up a Dollar General product by UPC
- Compare Dollar General prices with other retailers, or monitor them
Setup
Get a free API key at scavio.dev (50 free credits to get started, no card required):
export SCAVIO_API_KEY=sk_live_your_key
If you do not have a key yet
An agent running this skill without SCAVIO_API_KEY set will get 401 on every
call below. The whole path from nothing to a working key is self-serve:
- Sign up at dashboard.scavio.dev - email or Google, no card required.
- A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
- A new account starts with 50 credits. Every endpoint in this skill costs 1 credit.
When the balance runs out the API answers 402 with a JSON body carrying
billing_url. Topping up needs no code change - the same key keeps working.
Every request is a POST with a JSON body and:
Authorization: Bearer $SCAVIO_API_KEY
Endpoints
Base URL: https://api.scavio.dev. All Dollar General endpoints cost 1 credit.
| Endpoint | Credits | What it returns |
|---|---|---|
POST /api/v1/dollargeneral/search | 1 | 24 results per page at one store: price, original price, available_quantity (units on hand at that store), rating, review count, categories, digital coupons, UPC and URL |
POST /api/v1/dollargeneral/product | 1 | One product by UPC at one store: price, original price, units on hand, nearby_stores_with_stock, rating, SKU, brand, description, highlights, images, categories and coupons |
POST /api/v1/dollargeneral/stores | 1 | Up to 25 stores near a ZIP or coordinates, nearest first: store_id, address, phone, coordinates, distance, hours, services. With upc, each store's unit count of that product |
POST /api/v1/dollargeneral/deals | 1 | Items on_sale or on clearance, priced and stocked at one store, 24 per page |
POST /api/v1/dollargeneral/coupons | 1 | Current digital coupons, 30 per page: offer id and code, summary, brand, value, offer type, category, minimum quantity, start and expiration dates |
Workflow
Every price and unit count belongs to one store, so pin the store first.
- Pick the store: call
/dollargeneral/storeswith the user'szip(orlatitudeandlongitude). Each row has astore_id. - Search at that store: call
/dollargeneral/searchwithqueryandstore_id. Each row has aupc. - One product in full: call
/dollargeneral/productwith theupcandstore_id. - Who has it nearby: call
/dollargeneral/storeswith thezipand theupc. One call returns the unit count at up to 25 nearby stores. - Deals and coupons: call
/dollargeneral/dealswithstore_idandtype, and/dollargeneral/coupons(not store-scoped).
Parameters
Search (/search)
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | required | Keywords (1-200 chars) |
store_id | string | required | Store number from /stores, e.g. "12629" |
page | integer | 1 | 1-based page (1-100), 24 results per page |
sort | string | recommended | recommended, price_low, price_high or rating |
in_stock_only | boolean | false | Only products with units on hand at the store |
Product (/product)
| Parameter | Type | Default | Description |
|---|---|---|---|
upc | string | required | Product UPC, the upc of a search result (6-14 digits, leading zeros optional) |
store_id | string | required | Store number |
Stores (/stores)
| Parameter | Type | Default | Description |
|---|---|---|---|
zip | string | one of | US ZIP code to search around |
latitude, longitude | number | one of | Coordinates to search around, instead of zip |
radius | number | 25 | Search radius in miles, 1-100 |
upc | string | - | Product UPC; every store also gets its unit count of that product |
Deals (/deals)
| Parameter | Type | Default | Description |
|---|---|---|---|
store_id | string | required | Store number |
type | string | required | on_sale (everything on sale) or clearance (the clearance event) |
page | integer | 1 | 1-based page (1-100), 24 per page |
sort | string | recommended | recommended, price_low, price_high or rating |
Coupons (/coupons)
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | 1-based page (1-50), 30 coupons per page |
Examples
curl -X POST https://api.scavio.dev/api/v1/dollargeneral/stores \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"zip": "75203", "upc": "030772156629"}'
Captured response (Bounty paper towels near Dallas 75203; trimmed to 2 of 25 stores):
{
"data": {
"zip": "75203",
"latitude": 32.744,
"longitude": -96.802,
"radius_miles": 25,
"upc": "030772156629",
"total_results": 117,
"count": 25,
"stores": [
{
"store_id": "12629",
"address": "2919 Cedar Crest Blvd",
"city": "Dallas",
"state": "TX",
"zip": "75203-4011",
"latitude": 32.741674,
"longitude": -96.788919,
"phone": "6822731392",
"distance_miles": 0.8,
"hours": { "monday": "08:00-20:00", "tuesday": "08:00-20:00", "wednesday": "08:00-20:00", "thursday": "08:00-20:00", "friday": "08:00-20:00", "saturday": "08:00-20:00", "sunday": "08:00-20:00" },
"services": ["Rug Doctor", "DG Delivery", "NCI", "Fresh Produce"],
"quantity": 3,
"in_stock": true,
"inventory_status": 3,
"is_sellable": true,
"pickup_eligible": false,
"delivery_eligible": true
},
{
"store_id": "19292",
"address": "655 W Illinois Ave Ste 254",
"city": "Dallas",
"state": "TX",
"zip": "75224-1814",
"latitude": 32.722557,
"longitude": -96.83183,
"phone": "4692502773",
"distance_miles": 2.3,
"hours": { "monday": "08:00-22:00", "tuesday": "08:00-22:00", "wednesday": "08:00-22:00", "thursday": "08:00-22:00", "friday": "08:00-22:00", "saturday": "08:00-22:00", "sunday": "08:00-22:00" },
"services": ["Amerigas", "DG Delivery", "NCI", "Alcohol", "Beer", "Wine"],
"quantity": 4,
"in_stock": true,
"inventory_status": 3,
"is_sellable": true,
"pickup_eligible": false,
"delivery_eligible": true
}
]
},
"response_time": 6114,
"credits_used": 1
}
A captured /product answer for the same UPC at store 12629 (description, images, categories and coupons trimmed):
{
"upc": "030772156629",
"sku": "36158202",
"store_id": "12629",
"title": "Bounty Paper Towels Select-A-Size White, 6 Double Plus Rolls, 103 Sheets Per Roll",
"brand": "Bounty",
"price": 14.95,
"original_price": 16.75,
"available_quantity": 3,
"in_stock": true,
"stock_status": 3,
"is_sellable": true,
"nearby_stores_with_stock": 20,
"rating": 4.5,
"review_count": 5680,
"unit_size": "305",
"unit_of_measure": "sq feet",
"url": "https://www.dollargeneral.com/p/bounty-paper-towels-select-a-size-white-6-double-plus-rolls-103-sheets-per-roll/030772156629"
}
import requests
BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def dg(endpoint, body):
r = requests.post(f"{BASE}/api/v1/dollargeneral/{endpoint}", headers=HEADERS, json=body, timeout=120)
r.raise_for_status()
return r.json()["data"]
# 1. The user's store
store = dg("stores", {"zip": "75203"})["stores"][0]
sid = store["store_id"]
# 2. Search at that store
row = dg("search", {"query": "paper towels", "store_id": sid})["products"][0]
print(row["title"][:60], row["price"], "on hand:", row["available_quantity"])
# 3. Unit count at every nearby store in one call
for s in dg("stores", {"zip": "75203", "upc": row["upc"]})["stores"]:
if s["in_stock"]:
print(s["store_id"], s["address"], s["distance_miles"], "mi:", s["quantity"], "units")
# 4. Clearance in stock at this store (the listing covers the whole chain)
clr = dg("deals", {"store_id": sid, "type": "clearance"})["products"]
print([p["title"][:40] for p in clr if p["available_quantity"]])
Response shapes
Every response uses the envelope { data, response_time, fetched_at, credits_used, credits_remaining }. Nothing is cached; fetched_at is when Dollar General answered.
- search / deals -
query(search) ortypeandcategory(deals),store_id,page,total_results,total_pages,count,products[](position,upc,sku,title,image,price,original_price,available_quantity,in_stock,inventory_status,is_sellable,rating,review_count,categories[],coupons[],offers[],url). - product -
upc,sku,store_id,title,brand,price,original_price,available_quantity,in_stock,stock_status,is_sellable,nearby_stores_with_stock,rating,review_count,unit_size,unit_of_measure,description,highlights[],images[],category_hierarchy[],categories[],coupons[],offers[],url. - stores -
zip,latitude,longitude,radius_miles,upc,total_results,count,stores[](store_id,address,city,state,zip,latitude,longitude,phone,distance_miles,hours{monday..sunday:"08:00-20:00"},services[], and withupc:quantity,in_stock,inventory_status,is_sellable,pickup_eligible,delivery_eligible). - coupons -
page,total_results,total_pages,count,coupons[](offer_id,offer_code,summary,description,brand,value,category,min_quantity,is_manufacturer_coupon,expiration_date,image,company,offer_type,start_date,disclaimer). The same coupon shape is attached to products incoupons[].
Guardrails
- Prices are in dollars:
14.95is $14.95. available_quantity(search, deals, product) andquantity(stores) are units on hand at that store.inventory_status/stock_statusare the site's raw codes; use the counts andin_stockwhen answering.- Vendor-stocked lines report a flat 5 rather than a real count: Frito-Lay chips (Doritos, Lay's) read exactly 5 at every store checked. Treat a 5 on those as "in stock", not "5 left".
valueis the coupon's dollar amount. Spend-threshold rewards ("Spend $30, Save $10") take it from the summary; when there is no amount to read, it isnull.- The deals listing and its
total_resultscover the whole chain, so out-of-stock items are included. Onlyavailable_quantity > 0means the item is at that store. - Clearance items carry the current price only:
original_priceequalspricethere, so do not report a discount for them. - Dollar General returns
ratingandreview_countonly; there is no review text endpoint. - A coupon's
offer_typecan beAmountOfforCashback; say which, and quoteexpiration_date. - Never fabricate prices, stock or coupons. Only return what the API returned, with the product
url.
Failure handling
400means a missing or invalid parameter (nostore_id, a UPC that is not numeric, neitherzipnor coordinates on/stores, an unknown ZIP, or atypeother thanon_saleorclearance).401means the API key is invalid or missing. CheckSCAVIO_API_KEY.402means the balance is out of credits. The body carriesbilling_url.404on/productmeans an unknown UPC or store number; check both. Not charged. A search at an unknown store answers with 0 results instead.429means rate or usage limit exceeded. Wait before retrying. See rate limits.502means Dollar General is temporarily unavailable. It is not charged; retry after a few seconds.
SDKs
pip install scavio==0.31.0
npm install scavio@0.31.0
import { Scavio } from "scavio";
const scavio = new Scavio(); // reads SCAVIO_API_KEY
const { data: near } = await scavio.dollarGeneral.stores({ zip: "75203" });
const store_id = near.stores[0].store_id;
const found = await scavio.dollarGeneral.search({ query: "paper towels", store_id });
const nearby = await scavio.dollarGeneral.stores({ zip: "75203", upc: found.data.products[0].upc });
const coupons = await scavio.dollarGeneral.coupons({ page: 1 });
MCP: the Scavio MCP server exposes all 5 endpoints as tools (search_dollar_general, get_dollar_general_product, get_dollar_general_stores, get_dollar_general_deals, get_dollar_general_coupons). Dollar General is opt-in: add dollargeneral to SCAVIO_PLATFORMS.
{
"mcpServers": {
"scavio": {
"command": "npx",
"args": ["-y", "@scavio/mcp-server@0.29.0"],
"env": {
"SCAVIO_API_KEY": "sk_live_your_key",
"SCAVIO_PLATFORMS": "default,dollargeneral"
}
}
}
}
Docs
Full reference per endpoint: search, product, stores, deals, coupons. Overview: Dollar General API.
Related skills
- Downloads
- 177All time
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v1.0.1
- License
- MIT-0
