Skip to content

Importing and Exporting Store Credit Balances

Store Credit reads and writes balances as CSV, which is what you need when migrating from another platform or when auditing balances in a spreadsheet. Export and import use the same column layout, so a file that comes out of one goes into the other.

Exporting Every Balance

Customers → Export Store Credit (CSV) downloads all current balances as store_credit_balances.csv. The file has four columns:

Column Contents
email The customer's email address.
website The website code, not its numeric ID.
amount The current balance.
currency The base currency the balance is held in.

The export writes the balance projection, so it is a snapshot of what customers can spend right now, not the full history. For the history, read the credit history in the admin or the ledger through the REST API.

Values that begin with a character a spreadsheet would treat as a formula are neutralized on the way out, so opening the file cannot execute anything.

Importing Starting Balances

Import runs through Magento's standard import tool at System → Data Transfer → Import. Choose Store Credit Balances as the entity type, leave the behavior as Add/Update, upload your file, and use Check Data before importing as you would for any Magento import.

The importer accepts five columns. email, website, and amount are required on every row:

Column Required Contents
email Yes An existing customer's email address. The customer must already exist on the given website.
website Yes The website code the balance belongs to.
amount Yes The balance to set, as a positive number.
reason No An internal note for the ledger entry. Defaults to CSV import.
currency No The currency code for the balance. Defaults to the website's base currency.

A minimal file looks like this:

email,website,amount,reason,currency
customer@example.com,base,25.0000,Migrated from legacy platform,EUR
another@example.com,base,140.0000,Migrated from legacy platform,EUR

Each imported row writes an Imported entry to the ledger with source import, so migrated balances arrive with an audit trail rather than appearing from nowhere.

Import Sets a Starting Balance, It Does Not Top Up

A row is skipped when the customer already has any store credit history on that website, with the message "Skipped [email] on [website]: customer already has store credit history." Import is for seeding balances on a fresh install, not for adding credit to accounts that are already in use. To change a balance that already has history, adjust it in the admin or use the REST API.

Rows That Will Be Rejected

  • Missing email or website - both are required, and a row without either is reported as emailIsRequired or websiteIsRequired.
  • A missing or non-numeric amount - amount is required as well, and a row where it is empty or not a number is reported as amountIsInvalid.
  • A negative amount - an imported balance cannot be negative. Import a zero balance instead, then subtract in the admin if you genuinely need a debit recorded.
  • An unknown email or website - the customer has to exist on that website already, so import customers before their balances.

Keeping the Numbers Trustworthy After a Bulk Change

Balances are a projection of the ledger, maintained as entries are written. After an unusual event, such as an import that was interrupted or a direct change to the database, you can have the projection rebuilt from the ledger and verified:

bin/magento hyva:store-credit:rebuild-balances

The command replays the ledger, rewrites the projection, and then checks both the projection and the ledger chain, reporting any discrepancy it finds. See Rebuilding the Balance Projection.