Sample Files

Download a sample spreadsheet to see the structure for importing customer data:

Customer Sample with Custom Fields - General customer import template with name, email, address, tags, and notes
Add Tags to Customers by Email - Update existing customers with tags using email address

General

ID

Description	Example Value
Shopify's unique customer identifier	`789012`

If present, the ID will be used to find an existing customer on the store. When importing, the ID will be used to see if the customer already exists. If there's no ID match the app will attempt to find an existing customer using the Email.

Email

Description	Example Value
Customer's email address	`[email protected]`

The customer's email address is used as the unique identifier for the customer account. This is also used for grouping multiple rows together and finding an existing customer on the store if the ID is not present.

Command

Description	Example Value
Action to perform: MERGE, DELETE, NEW	`MERGE`

MERGE: Update existing customer or create if not found
DELETE: Remove the customer from the store (will skip if customer doesn't exist)
NEW: Create a new customer (will skip if customer already exists)

First Name

Description	Example Value
Customer's first name	`Jane`

The customer's given name.

Last Name

Description	Example Value
Customer's last name	`Smith`

The customer's family name or surname.

Phone

Description	Example Value
Customer's phone number	`+1-555-0123`

The customer's primary phone number.

Language

Description	Example Value
Customer's preferred language	`en`

The customer's preferred language code (e.g., en for English, fr for French).

State

Description	Example Value
Account state: ENABLED, DISABLED	`ENABLED`

ENABLED: Customer account is active and can place orders
DISABLED: Customer account is disabled and cannot place orders

Note

Description	Example Value
Internal notes about the customer	`VIP customer`

Internal notes that staff can add about the customer. These are not visible to the customer.

Tags Command

Description	Example Value
Tag action: MERGE, REPLACE, DELETE	`MERGE`

MERGE: Add the specified tags to existing tags
REPLACE: Replace all existing tags with specified tags
DELETE: Remove the specified tags from the customer

Tax Exempt

Description	Example Value
Whether customer is exempt from taxes	`FALSE`

TRUE: Customer is exempt from paying taxes
FALSE: Customer is subject to applicable taxes

Email Marketing: Status

Description	Example Value
Email marketing subscription status	`SUBSCRIBED`

SUBSCRIBED: Customer has opted in to receive marketing emails
NOT_SUBSCRIBED: Customer has not opted in or has unsubscribed
PENDING: Subscription is pending confirmation

On import, if the customer account has no email address, this field is skipped.

Email Marketing: Level

Description	Example Value
Email marketing opt-in level	`CONFIRMED_OPT_IN`

SINGLE_OPT_IN: Customer signed up with single opt-in
CONFIRMED_OPT_IN: Customer confirmed their subscription via email
UNKNOWN: Opt-in level is not known

SMS Marketing: Status

Description	Example Value
SMS marketing subscription status	`SUBSCRIBED`

SUBSCRIBED: Customer has opted in to receive SMS marketing
NOT_SUBSCRIBED: Customer has not opted in or has unsubscribed
PENDING: Subscription is pending confirmation

On import, if the customer account has no phone number, this field is skipped.

Created At

Description	Example Value
Date and time when account was created	`2023-01-15 10:00:00 -0500`

The timestamp when the customer record was originally created in Shopify. This field is export-only and cannot be imported or changed to a specific date.

Updated At

Description	Example Value
Date and time when account was last modified	`2023-06-20 15:30:00 -0500`

The timestamp when the customer account was last modified or updated. This field is export-only and cannot be imported.

Addresses

Top Row

Description	Example Value
Whether this is the first row for this customer	`TRUE`

TRUE: This is the primary row for the customer
FALSE: This is a secondary row (e.g., for addresses or additional data)

Row

Description	Example Value
Row number for multi-row data	`2`

Used when a customer spans multiple rows (e.g., when including multiple addresses).

Address: ID

Description	Example Value
Unique identifier for the address	`345678`

The unique identifier for a specific address associated with the customer.

Address: Command

Description	Example Value
Action to perform: MERGE, UPDATE, NEW, DELETE, REPLACE	`MERGE`

Address matching uses the Address: ID column. Numeric IDs from a previous Altera export are accepted, as is the full Shopify GID (gid://shopify/MailingAddress/12345). When no Address: ID is given, MERGE instead compares the full address content.

MERGE: If Address: ID matches an existing address on the customer, that address is updated in place. If no Address: ID is given, the incoming address is compared against the customer's existing addresses by full content - an identical address is left untouched (no duplicate is created), and any difference (even a single field such as Company or Phone) is added as a new address rather than edited in place. Other addresses on the customer are always left untouched.
UPDATE: Update an existing address by Address: ID. If Address: ID is missing or does not match an existing address on the customer, the row is skipped with a warning. No new addresses are ever created.
NEW: Create a new address. If Address: ID matches an existing address on the customer, the row is skipped with a warning.
DELETE: Remove the address identified by Address: ID. Skipped with a warning if no matching address is found.
REPLACE: Delete every existing address on the customer, then create the addresses in the import file. Use carefully - any addresses not in the import are removed.

Address: First Name

Description	Example Value
First name for this address	`Jane`

The first name associated with this specific address. This field is optional, if you only have one name you should place it in the Address: Last Name field instead.

Address: Last Name

Description	Example Value
Last name for this address	`Smith`

The last name associated with this specific address. This field is required when creating an address.

Address: Company

Description	Example Value
Company name for this address	`Acme Inc`

The company name associated with this address, if applicable.

Address: Phone

Description	Example Value
Phone number for this address	`+1-555-0123`

The phone number associated with this specific address.

Address: Line 1

Description	Example Value
Street address	`123 Main St`

The primary street address line.

Address: Line 2

Description	Example Value
Additional address details	`Suite 100`

Additional address information like apartment, suite, or unit number.

Address: City

Description	Example Value
City	`New York`

The city for this address.

Address: Province

Description	Example Value
State/province	`New York`

The state, province, or region for this address.

Address: Zip

Description	Example Value
Postal/zip code	`10001`

The postal or zip code for this address.

If your zip code starts with zeros (like 01234), Excel may strip the leading zeros. To prevent this, start the zip code with a single quote: '01234. The quote will be automatically removed during import.

Address: Country

Description	Example Value
Country	`United States`

The country for this address. When importing, Altera will automatically convert country names to their ISO two-letter codes (e.g., "USA", "U.S.A.", "United States", "UK", "Great Britain" are all recognized). You can also provide the country code directly (e.g., US, CA, GB).

Address: Is Default

Description	Example Value
Whether this is the default address	`TRUE`

TRUE: This is the customer's default address
FALSE: This is an additional address

First and Last Order

Total Orders

Description	Example Value
Number of orders placed	`25`

The total number of orders the customer has placed. This field is export-only and cannot be imported.

Total Spent

Description	Example Value
Total amount spent by customer	`2499.99`

The total amount the customer has spent across all orders. This field is export-only and cannot be imported.

First Order: ID

Description	Example Value
ID of customer's first order	`1001`

The unique identifier of the customer's first order. This field is export-only and cannot be imported.

Last Order: ID

Description	Example Value
ID of customer's most recent order	`1025`

The unique identifier of the customer's most recent order. This field is export-only and cannot be imported.

Activation URLs

Account Activation URL

Description	Example Value
URL for customer to activate account	`https://shop.myshopify.com/account/activate/...`

A secure URL that customers can use to activate their account. This field is export-only and cannot be imported.

Store Credit

Store credit allows you to issue credit amounts to customers that they can use for future purchases. Each customer can have multiple store credit accounts in different currencies.

Exporting the Store Credit Transactions column group requires the read_store_credit_account_transactions Shopify access scope. The first time you tick the column group in the export configurator the app will prompt you to authorize.

Store Credit: Currency

Description	Example Value
Currency code for the store credit account	`USD`

The three-letter currency code (ISO 4217) for the store credit account. Each customer can have separate store credit accounts for different currencies. Defaults to the store's currency code.

Note: If no store credit account exists for the specified currency, Shopify will automatically create one with a starting balance of 0 when the first credit operation is performed.

Store Credit: Balance

Description	Example Value
Current balance of the store credit account - Export only	`25.00`

The current remaining balance of the customer's store credit account. Export-only - to add, set, or debit a specific amount, use the Store Credit Transactions columns below.

Store Credit Transactions

Use these columns to issue, debit, or set the balance of a customer's store credit account. Each transaction is its own row. When a customer has multiple transactions across multiple currencies, repeat the customer's email or ID on each row and fill Store Credit: Currency only on the first row of each account.

Store Credit Transaction: ID

Description	Example Value
Shopify-generated transaction ID	`280328273935`

The ID of the store credit transaction. Filled in by export. On import, leave blank to create a new transaction. Filled values are used to dedupe re-imports - if the transaction already exists on the customer, it will be skipped.

Store Credit Transaction: Command

Description	Example Value
Type of transaction to apply	`CREDIT`

Controls the direction of the transaction. Required when adding new transactions.

CREDIT - Adds the amount to the customer's store credit balance.
DEBIT - Subtracts the amount from the customer's store credit balance.
SET - Sets the balance to a specific amount. Altera will automatically credit or debit the difference between the current balance and the target amount.

Store Credit Transaction: Amount

Description	Example Value
Transaction amount as a positive decimal	`25.00`

The transaction amount. Always a positive number - the Command column controls the direction. On export, debit transactions appear as negative numbers (matching how the source system records them).

Store Credit Transaction: Expire At

Description	Example Value
Expiration date for a CREDIT transaction	`2027-01-01 00:00:00 +0000`

The date and time at which a CREDIT transaction expires. Only valid when Command is CREDIT. Must be in the future - past dates are ignored. ISO-formatted timestamps are also supported.

Store Credit Transaction: Send Receipt

Description	Example Value
Whether Shopify should email the customer about the credit	`FALSE`

If TRUE, Shopify sends an email notification to the customer when the credit is issued. Only valid when Command is CREDIT. Defaults to FALSE.

TRUE - Send a notification email.
FALSE - Do not send a notification email.

Store Credit Transaction: Created At

Description	Example Value
Date and time the transaction was created	`2026-05-06 03:38:40 -0400`

When the transaction was created in Shopify. Export only - cannot be set on import.

Store Credit Transaction: Event

Description	Example Value
The event that caused the transaction	`ADJUSTMENT`

The Shopify event that triggered the transaction. Export only.

Possible values include:

ADJUSTMENT - A manual credit/debit (the value emitted for transactions Altera writes).
EXPIRATION - A previously issued credit expired.
ORDER_PAYMENT - The customer used store credit to pay for an order.
ORDER_REFUND - An order refund issued store credit.
ORDER_CANCELLATION - An order cancellation refunded store credit.
PAYMENT_FAILURE - A failed payment reversed store credit.
PAYMENT_RETURNED - A returned payment reversed store credit.
TAX_FINALIZATION - A tax adjustment changed the credit amount.

Store Credit Transaction: Remaining Balance

Description	Example Value
Account balance after this transaction	`123.99`

The balance of the customer's store credit account immediately after the transaction. Export only.

Legacy Store Credit Columns

The following columns are import-only aliases kept for backwards compatibility with files exported by older versions of Altera. They keep working unchanged - new exports use the Store Credit Transactions columns above.

Store Credit: Amount (legacy)

Description	Example Value
Target balance for the store credit account	`25.00`

Sets the customer's store credit balance to the specified amount. Equivalent to a Store Credit Transaction: Command=SET row in the new format.

Store Credit: Adjust

Description	Example Value
Signed amount to credit or debit	`-15.50`

Positive values credit the account; negative values debit it. Equivalent to Store Credit Transaction: Command=CREDIT or Command=DEBIT in the new format.

Store Credit: Expires At (legacy)

Description	Example Value
Expiration date for the credit	`2027-01-01 00:00:00 +0000`

The expiration applied when using the legacy Store Credit: Amount or Store Credit: Adjust columns. The new Store Credit Transaction: Expire At is recommended.

Metafields

Metafields can be imported and exported with customers to store custom metadata and additional attributes.

For detailed information about working with metafields, see our Metafields guide.

Export Filters

You can use these filters to limit which customers are exported:

id: Filter by customer ID
customer_segment: Filter by customer segment. Requires the segment GID (e.g., gid://shopify/Segment/123456)
email: Filter by email address
orders_count: Filter by number of orders
order_date: Filter by order date - matches customers who placed any order during the specified period
last_order_date: Filter by the date of the customer's most recent order. This filter is applied after fetching data, so a count preview is not available when using it
total_spent: Filter by total spent amount
customer_date: Filter by customer creation date
tag: Filter by tag

Description	Example Value
Comma-separated list of tags	`vip, wholesale`

Customer Fields