> 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/analytics-data-and-account/bulk-import-credit-csv.md).

# Bulk import credit (CSV)

{% hint style="info" %}
**Plan:** bulk import is a plan-gated feature; check your plan's feature list. It is also blocked entirely on development stores.
{% endhint %}

{% embed url="<https://dollarlabs.neetorecord.com/watch/5556c4b90df71d34cc86>" %}

*This article's section starts at 0:00 in the video.*

When you're done, you'll have credited (or debited) store credit for a whole list of customers from one CSV file. It's the tool for migrations, compensation batches, and B2B credit. This article is the full contract: the exact file format, how jobs run, and how errors are handled.

## Prerequisites

* A plan that includes bulk import (see [Plans, usage & overage billing](/dollarback-store-credit/analytics-data-and-account/plans-usage-and-overage-billing.md)).
* A live store; imports are blocked on development stores.
* Your customers already exist in Shopify; the import matches rows to existing customers, it doesn't create them.

## The CSV format

| Header              | Required                  | Notes                                                                                                                            |
| ------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `Amount`            | Yes                       | Positive number. Quoted fields and thousand separators are handled: `"8,260.90"` parses fine.                                    |
| `Currency`          | Yes                       | The currency code for the row's amount.                                                                                          |
| `Email`             | One of Email / CustomerId | Matches the Shopify customer by email.                                                                                           |
| `CustomerId`        | One of Email / CustomerId | Matches by Shopify customer ID. **When both are present, CustomerId wins**: a wrong ID fails the row even if the email is right. |
| `CompanyLocationId` | B2B mode only             | Required on every row when the job runs in B2B mode; the credit attaches to the company location instead of a customer.          |

Additional constraints:

* **File size:** 5 MB maximum. Split larger files into multiple jobs.
* **Amounts are always positive.** Whether the job credits or debits is set on the job, not per row.
* **Duplicates are not deduped.** Two rows for the same customer credit that customer twice. Clean your file before importing.

## Run an import

1. Open **DollarBack admin → Bulk import**.
2. In the **Upload CSV File** section, click **Choose CSV File** and select your file.
3. Set **Action Type**: **Credit** or **Debit**.
4. For credits, set **Expiry Days**: how many days until the imported credit expires. `0` (the default) means never expires. The field is disabled for debits; expiry applies to credits only.
5. Choose your toggles:
   * **Notify Customers**, "Send notification email to customers": each credited customer gets the store-credit-credited email.
   * **Send to Integrations**, "Send event integrations": emits the credited/debited events to Klaviyo, Omnisend, and Shopify Flow, exactly as an organic credit would.
   * **B2B Mode**, "Apply store credit to a company location. CSV must include a CompanyLocationId column." See [B2B store credit](/dollarback-store-credit/analytics-data-and-account/b2b-store-credit.md).
6. Click **Import CSV**.

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-dace5f2f18c533bf301275548907c1715fd48035%2Fdb-bulk-import-form-annotated.png?alt=media" alt="The Bulk Import page with the Upload CSV File card (Action Type, Expiry Days, Notify Customers, Send to Integrations, B2B Mode, Reason, Download Sample CSV, Choose CSV File) and the CSV Format Requirements card."><figcaption><p>Set the action, expiry and options, then choose your CSV; the Import CSV button appears once a file is selected.</p></figcaption></figure>

{% hint style="warning" %}
Think before enabling **Notify Customers** on a large migration import: every row sends an email. For silent migrations, leave it off.
{% endhint %}

## How jobs run

A job moves through: **pending → processing → completed / failed / stopped**.

* **Rows commit individually**, in small batches. There is no all-or-nothing transaction: a job that fails halfway has still applied everything it processed.
* **Stop Import** halts the job but **keeps all rows already processed**. Don't re-run the same file after a stop; the processed customers would be credited again.
* **There is no automatic per-row retry.** A failed row stays failed until you fix it and import a corrected file containing only those rows.
* **Unknown customers don't kill the job.** A row whose Email/CustomerId matches no customer is logged as "Customer not found" and processing continues with the next row.

## Read the job log

Each job in the history keeps a downloadable log with one entry per row:

<figure><img src="https://2844543096-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcVBfwy7Yj4tU8TsxkHEr%2Fuploads%2Fgit-blob-aa669f5ce9ea53ad14527a0a85457247c5fa4214%2Fdb-bulk-import-history-annotated.png?alt=media" alt="The Bulk Import History table with one completed credit import, its progress, success and error counts, start and finish times, and a Download Logs link."><figcaption><p>Every import is listed in the history; download its log to see which rows failed and why.</p></figcaption></figure>

| Log column     | Contents                                                   |
| -------------- | ---------------------------------------------------------- |
| Customer ID    | The row's resolved (or attempted) customer ID.             |
| Customer Email | The row's email.                                           |
| Action Type    | Credit or debit.                                           |
| Amount         | The row's amount.                                          |
| Currency       | The row's currency.                                        |
| Status         | Whether the row succeeded or failed.                       |
| Message        | The per-row reason on failure (e.g. "Customer not found"). |
| Timestamp      | When the row was processed.                                |

## Verify it works

Run a tiny test file first: two or three rows including yourself. After the job completes, check the customers' balances, then confirm the rows also appear in **Analytics → Activity**, under the **Credits earned** view. Remember that imports count toward outstanding liability but are excluded from the Overview's **Cashback issued** card and all campaign figures; see [Understand your analytics](/dollarback-store-credit/analytics-data-and-account/understand-your-analytics.md).

## Common issues

* Rows failed with "Customer not found", the upload was rejected, or a job stopped early: see [My bulk import failed](/dollarback-store-credit/troubleshooting-and-faq/bulk-import-failed.md) for the full diagnosis checklist.
* A customer was credited twice: the file contained two rows for them, or the same file was imported twice; duplicates are not deduped.
* The page says bulk import isn't available: plan gate or development store; see the hint at the top.

## Related articles

* [My bulk import failed](/dollarback-store-credit/troubleshooting-and-faq/bulk-import-failed.md)
* [B2B store credit](/dollarback-store-credit/analytics-data-and-account/b2b-store-credit.md)
* [Migrating from another loyalty app](/dollarback-store-credit/getting-started/migrating-from-another-loyalty-app.md)
* [Export balances & reports](/dollarback-store-credit/analytics-data-and-account/export-balances-and-reports.md)