# Black Friday & Store Sales Tracker — Coupons + Cashback (`smart-shopping-data/black-friday-sales-tracker`) Actor

Track sales, coupon codes and Black Friday offers for any store from Rakuten and TopCashback store pages (US, UK, AU): offer, code, % off, expiry and the cashback on top. Only-new mode for alerts. Pay per offer.

- **URL**: https://apify.com/smart-shopping-data/black-friday-sales-tracker.md
- **Developed by:** [smartshopping-data](https://apify.com/smart-shopping-data) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 store offers

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Black Friday & Store Sales Tracker — Coupons + Cashback

**Track the sales, coupon codes and Black Friday offers for any store in the US, UK and Australia, with the cashback you get on top. One row per offer: offer text, code, % off, sale event, expiry badge, cashback and link.**

Rakuten and TopCashback keep a page for each store listing its current offers: sitewide sales, coupon codes, free shipping and seasonal events. This Actor reads those pages for your stores and returns every offer in one format. Ask for Black Friday offers only, or schedule it with **Only new offers** to get alerts when a store launches a sale.

| Country | Offers from |
|---|---|
| 🇺🇸 US | Rakuten, TopCashback |
| 🇬🇧 UK | TopCashback |
| 🇦🇺 Australia | TopCashback |

### What you can do with it

- 🛍️ **Black Friday tracking:** follow when your stores' Black Friday and Cyber Monday offers go live, with codes and discounts.
- 🔔 **Sale alerts:** schedule it hourly with **Only new offers** and send new sales to email, Slack, Telegram or Discord.
- 💸 **Stack savings:** each offer shows the cashback rate, so you see the code and the cashback together.
- 📊 **Competitor and promo research:** see how often retailers run sales, how deep the discounts go and which events they use.

### Input

```json
{
  "stores": ["Macy's", "Nike", "Currys", "THE ICONIC"],
  "countries": ["US", "UK", "AU"],
  "onlyBlackFriday": true,
  "minDiscountPercent": 20,
  "onlyNew": true,
  "stateName": "bf-alerts"
}
```

| Field | What it does | Default |
|---|---|---|
| `stores` | Store names or websites. Empty checks a built-in list of big retailers in each country (20 US, 15 UK, 10 AU) | built-in list |
| `countries` | `US`, `UK`, `AU` | all three |
| `onlyBlackFriday` | Only offers mentioning Black Friday, Cyber Monday or Cyber Week | `false` |
| `onlyWithCode` | Only offers with a coupon code | `false` |
| `minDiscountPercent` | Only offers mentioning at least this % off | `0` |
| `keywords` | Only offers mentioning one of these words ("tv", "laptop") | all offers |
| `onlyNew` | Skip offers already returned by earlier runs (for alerts) | `false` |
| `stateName` | Separate memory for each schedule when using `onlyNew` | `default` |

### Output

One row per offer:

```json
{
  "id": "rakuten-us:macys:14632230",
  "store": "Macy's",
  "portal": "rakuten-us",
  "portalName": "Rakuten",
  "country": "US",
  "title": "Black Friday Sale: Take an extra 15-30% off.",
  "description": "Exclusions apply. Online only.",
  "code": "BEST",
  "offerType": "code",
  "maxDiscountPercent": 30,
  "freeShipping": false,
  "saleEvent": "Black Friday",
  "isBlackFriday": true,
  "isCyberMonday": false,
  "badge": "ENDS TOMORROW",
  "cashback": "6% Cash Back",
  "previousCashback": "2%",
  "storeCashback": "6%",
  "offerUrl": "https://www.rakuten.com/macys_8333-xfas?special=14632230",
  "storeUrl": "https://www.rakuten.com/shop/macys",
  "scrapedAt": "2026-11-20T12:00:00.000Z"
}
```

- `offerType` is `code`, `sale`, `free-shipping` or `cashback` (a cashback offer with no discount).
- `maxDiscountPercent` is the largest "% off" in the offer ("extra 15-30% off" gives 30); `null` when the offer names no percentage.
- `saleEvent` names the event the offer mentions: Black Friday, Cyber Monday, Singles Day, Click Frenzy, Boxing Day, Prime Day, Labor Day, Memorial Day, Presidents Day, Christmas, New Year, End of Season or Clearance.
- `badge` is the portal's label, such as "ENDS TOMORROW", or the expiry stated in the offer ("Expires 30th November").
- `cashback` is the cashback for this offer; `storeCashback` is the store's headline rate on that portal.
- The same store on two portals gives two sets of offers, since each portal lists its own.

The run's `SUMMARY` record counts the store pages and offers, the offers per sale event, and lists the biggest discounts found.

### Pricing

Pay per offer: you are only charged for offers saved to the dataset. Filters are applied first, and with **Only new offers**, runs where nothing changed cost nothing beyond Apify's small platform usage.

### Notes

- Offers are what the portal lists on its public store page. Some codes on TopCashback are only shown to signed-in members; those offers are returned without the code.
- Store names are matched to portal pages by name or website; if a store is missing, try its website (`currys.co.uk`) or the name as the portal spells it.
- Requests are spaced out to be gentle on the portals' sites.

### Related Actors

- [Cashback Rate Comparison](https://apify.com/Smart-Shopping-Data/cashback-rate-comparison): the best cashback for any store across Rakuten, TopCashback, BeFrugal, Capital One Shopping, Mr. Rebates and ShopBack (US, UK, AU).
- [Cashback Boost Monitor](https://apify.com/Smart-Shopping-Data/cashback-boost-monitor): alerts when cashback rates for your stores go up, go down or appear.
- [Rakuten Cashback Scraper](https://apify.com/Smart-Shopping-Data/rakuten-cashback-scraper): every Rakuten (US) store with its current rate.
- [TopCashback Scraper](https://apify.com/Smart-Shopping-Data/topcashback-scraper): every TopCashback store in the US, UK and Australia with its current rate.
- [Deal Scraper](https://apify.com/Smart-Shopping-Data/deal-community-scraper): the latest Slickdeals, hotukdeals and OzBargain deals, with keyword alerts.

### Support

Missing a store, a country or a field? Open an issue on the **Issues** tab.

*Offers are read from Rakuten's and TopCashback's public pages and change often. Check the store before buying. Not affiliated with Rakuten, TopCashback or the stores listed.*

# Actor input Schema

## `stores` (type: `array`):

Store names or websites, e.g. Macy's, nike.com, Currys. Leave empty to check a built-in list of big retailers in each country.

## `countries` (type: `array`):

US uses Rakuten and TopCashback; UK and AU use TopCashback.

## `onlyBlackFriday` (type: `boolean`):

Only save offers that mention Black Friday, Cyber Monday or Cyber Week.

## `onlyWithCode` (type: `boolean`):

Only save offers that come with a coupon code.

## `minDiscountPercent` (type: `integer`):

Only save offers mentioning at least this percentage off, e.g. 30. Offers without a percentage are skipped when this is set.

## `keywords` (type: `array`):

Only save offers whose text contains one of these words, e.g. tv, laptop, shoes.

## `onlyNew` (type: `boolean`):

Skip offers already returned by earlier runs. Use with a schedule for alerts.

## `stateName` (type: `string`):

Use a different name for each schedule so they don't share memory.

## Actor input object example

```json
{
  "stores": [
    "Macy's",
    "Nike",
    "Best Buy",
    "Currys",
    "John Lewis",
    "THE ICONIC"
  ],
  "countries": [
    "US",
    "UK",
    "AU"
  ],
  "onlyBlackFriday": false,
  "onlyWithCode": false,
  "minDiscountPercent": 0,
  "keywords": [],
  "onlyNew": false,
  "stateName": "default"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "stores": [
        "Macy's",
        "Nike",
        "Best Buy",
        "Currys",
        "John Lewis",
        "THE ICONIC"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("smart-shopping-data/black-friday-sales-tracker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "stores": [
        "Macy's",
        "Nike",
        "Best Buy",
        "Currys",
        "John Lewis",
        "THE ICONIC",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("smart-shopping-data/black-friday-sales-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "stores": [
    "Macy'\''s",
    "Nike",
    "Best Buy",
    "Currys",
    "John Lewis",
    "THE ICONIC"
  ]
}' |
apify call smart-shopping-data/black-friday-sales-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,smart-shopping-data/black-friday-sales-tracker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vNedSVuaSFLLdIVWT/builds/bhytJK9Vzm2l7t8es/openapi.json