> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/earning-cashback-programs/backfill-cashback-for-past-orders.md).

# Backfill cashback for past orders

{% hint style="info" %}
**Plan:** Enterprise plan. On other plans the page shows *"Order backfill isn't included in your current plan. Contact support to enable it."*; reach out through the in-app chat if you need it switched on.
{% endhint %}

Installed DollarBack on a store that has been trading for years? Backfill replays orders placed **before DollarBack was active** through your current cashback rules, so long-standing customers start with a balance instead of from zero. By the end of this page you'll have previewed a backfill, checked the results, and credited the orders you chose.

## What a backfill does

* Replays each selected order through your **active purchase cashback programs**, exactly as they're configured today, and saves a cashback breakdown to the order. You can see it on the order page in Shopify admin; see [Admin blocks on the customer & order pages](/dollarback-store-credit/analytics-data-and-account/admin-blocks-customer-and-order-pages.md).
* Optionally **credits the customer** with the calculated store credit.
* **Sends no DollarBack email and fires no integrations.** No Credited email, no Klaviyo, Omnisend, or Flow events. Customers find the credit in the widget and at checkout. The one exception is opt-in: **Notify customers about their store credit** sends *Shopify's* own store credit notification, not a DollarBack one (see Step 3).
* **Skips orders DollarBack has already processed**, so re-running over the same period is safe: those orders show up in the results as already processed, with the previously credited amount alongside what the rules would pay today, and are never touched.
* Doesn't count towards your plan's monthly order allowance. Backfilled orders aren't billable usage.

## Before you start

Backfill uses your **current** setup, not the setup that existed when the order was placed. Check these first:

* **Programs**: only enabled purchase programs inside their start/end dates *today* take part. A seasonal program that has ended won't apply to orders from that season; a program you started this morning will apply to orders from last year. Discount-code reward programs are skipped; only store-credit programs are replayed. See [Set up purchase cashback](/dollarback-store-credit/earning-cashback-programs/set-up-purchase-cashback.md).
* **Tiers**: if tiers are enabled, each customer's **current** tier decides their multiplier and which programs they can earn from, so run a tier sync first ([Sync tiers to customers](/dollarback-store-credit/loyalty-tiers/sync-tiers-to-customers.md)). Customers with no tier assigned are skipped.
* **Settings** apply as usual: calculation base, store-credit and gift-card handling, excluded customer tags, maximum cashback per order, round-up. Two settings **don't** apply: the trigger event (use the order-status filter below instead) and the **holding period**. Backfilled credit is spendable immediately.
* **Refunds and edits** are already netted out, because the replay uses each order's current line items and totals. Fully cancelled orders are *not* skipped automatically, so filter by status or use a CSV if you want to leave them out.

## Step 1: Open the backfill page

On the DollarBack home page, find the **Backfill past orders** card (*"Apply cashback to historical orders"*) and click **Open**. The page is titled *"Backfill past orders — Apply your current cashback rules to orders placed before DollarBack was active."*

## Step 2: Choose which orders

In the **New backfill** card, pick one of two ways to select orders:

| Mode                 | How it selects                                                                                 | Notes                                                                                                                                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Date range**       | Every order created between the two dates (end date inclusive), defaulting to the last 90 days | Add an **Order status** filter: **Any status**, **Paid only**, or **Fulfilled only**                                                                                                                     |
| **CSV of order IDs** | Exactly the orders listed in your file                                                         | Needs an `orderId` column of numeric Shopify order IDs; other columns are ignored; maximum 100 KB. Duplicate IDs are collapsed. IDs that don't exist in your store are reported as not found and skipped |

There's no limit on how old the orders can be or how many you select. Large ranges simply take longer.

## Step 3: Choose the mode

Three checkboxes decide what the run writes. The first two set the mode:

| Credit customers with the calculated store credit | Dry run | What happens                                                                                                                                 |
| ------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| off                                               | **on**  | **Dry run.** Nothing is written to orders or customers. You get a downloadable CSV of what each order's outcome would have been. Start here. |
| off                                               | off     | **Preview only** (the default). The cashback breakdown is saved to each order, but no store credit is issued and no emails are sent.         |
| **on**                                            | off     | **Credit.** The breakdown is saved *and* store credit is issued immediately, with expiry per the program's settings.                         |

The third, **Notify customers about their store credit**, sits indented under **Credit customers** and is off by default. It only becomes available on a credited run — it stays greyed out while **Credit customers** is off or **Dry run** is on, because there is no credit to announce.

{% hint style="warning" %}
This checkbox sends **Shopify's own** store credit notification, not a DollarBack email. It is the only email a backfill can produce, and DollarBack's own templates and integrations stay silent either way. Turn it on deliberately: a backfill over several years of orders can mean thousands of customers hearing about a balance on the same afternoon. Leave it off if you would rather announce the credit yourself in a campaign.
{% endhint %}

{% hint style="warning" %}
**Preview only is not a rehearsal for a credited run.** Saving the breakdown marks those orders as processed, so a later credited run will list them as already processed and will *not* credit them. If you want to look before you credit, use **Dry run**, review the CSV, then run again with **Credit customers** on.
{% endhint %}

Click **Start backfill**. Only one backfill can run at a time per store; the button reads **Backfill in progress…** until it finishes.

## Step 4: Track progress and download the results

While a run is active, the **Recent backfills** card shows a progress bar and four counters: **Processed**, **Eligible**, **Credited**, and **Projected credit**, refreshing every few seconds. Each finished run keeps a status badge (queued, running, completed, or failed), a **Dry run** badge where relevant, and a **Download results** button. The card lists your ten most recent runs.

The results CSV has one row per order: `orderId`, `orderName`, `orderStatus`, `action`, `reason`, `previousCredit`, `projectedCredit`, `difference`, `currency`.

| `action`                                 | Meaning                                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `would_credit` / `would_write_metafield` | Dry run: what a real run would have done                                                                                  |
| `metafield_written`                      | Breakdown saved; no credit issued (preview only, or the order earned nothing)                                             |
| `credited`                               | Store credit issued                                                                                                       |
| `credit_duplicate`                       | This backfill credit already existed, so it wasn't issued twice                                                           |
| `credit_failed`                          | Shopify rejected the credit; re-run to retry those orders                                                                 |
| `already_processed`                      | DollarBack had already handled the order; `previousCredit` vs `projectedCredit` shows the difference, nothing was written |
| `not_found`                              | CSV mode: the order ID isn't in this store                                                                                |
| `error`                                  | The order couldn't be evaluated; see `reason`                                                                             |

Skipped orders carry the reason in `reason`: `no_customer` (guest checkout), `no_active_config`, `discount_code_excluded` (the order used a discount code and no program allows that), `no_tier` / `tier_not_configured`, `paid_with_store_credit`, `paid_with_gift_card`, `excluded_customer_tag`, or `no_cashback` (the rules produced $0).

Credited runs also appear in the credit log under **DollarBack admin → Analytics → Activity**, dated to the original order. See [Credit logs & scheduled rewards](/dollarback-store-credit/analytics-data-and-account/credit-logs-and-scheduled-rewards.md).

## Verify it works

1. Run a **Dry run** over a short range (a week) and download the CSV. Spot-check three `would_credit` rows against the orders in Shopify admin: does the projected credit match your program's rate on the eligible lines?
2. Run the same range with **Credit customers** on. The rows should now read `credited`, and the customers' balances should show the amounts in the widget or their customer page.
3. Run it a third time. Every row should read `already_processed` and no new credit should appear.

## Common issues

* **The page shows "Order backfill isn't included in your current plan"**: it's an Enterprise feature. Contact support through the in-app chat.
* **"A backfill is already in progress"**: one run per store at a time. Wait for the current one to complete or fail. If a run looks stuck for more than 15 minutes with no progress, contact support.
* **Credited run shows `already_processed` everywhere and no credit**: an earlier preview-only run saved the breakdowns. Those orders can't be credited by backfill; use [Bulk import credit (CSV)](/dollarback-store-credit/analytics-data-and-account/bulk-import-credit-csv.md) for a one-off top-up.
* **Lots of `no_tier` rows**: tiers are enabled but customers haven't been synced. Run [Sync tiers to customers](/dollarback-store-credit/loyalty-tiers/sync-tiers-to-customers.md) and re-run.
* **A program you expected didn't apply**: check it's enabled and its dates include today, not the order date.
* **"CSV is too large (max 100 KB)" or "No 'orderId' column with numeric values found"**: split the file, and make sure the column header is exactly `orderId` with numeric IDs (not `gid://` URLs).
* **A run failed**: the error is shown on the run's row. Re-running is safe; orders that were credited before the failure are reported as `credit_duplicate` or `already_processed`, not credited again.

## Related articles

* [How cashback is calculated](/dollarback-store-credit/earning-cashback-programs/how-cashback-is-calculated.md)
* [When credit is issued](/dollarback-store-credit/earning-cashback-programs/when-credit-is-issued.md)
* [Migrating from another loyalty app](/dollarback-store-credit/getting-started/migrating-from-another-loyalty-app.md)
* [Bulk import credit (CSV)](/dollarback-store-credit/analytics-data-and-account/bulk-import-credit-csv.md)
* [Plans, usage & overage billing](/dollarback-store-credit/analytics-data-and-account/plans-usage-and-overage-billing.md)