> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/shopify.md).

# Shopify scripts

Reference of the Shopify customer mapper script: registration, the MapFromShopify and MapToShopify handlers and an example.

The Shopify connector reads a Shopify customer to fill the wallet account and, during an enrolment whose flow has a `shopify` step, creates or updates the Shopify customer. The customer mapper script adjusts both directions beyond the default mapping. This page is the reference for `extensions.shopify.customerMapper`. The connector is described on the [Shopify connector page](https://docs.thewalletcrew.io/connectors/e-commerce/shopify.md); the rules shared by every connector script are in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md). The connector page documents no script today: this page is the only reference.

<details>

<summary><strong>Real-world examples</strong></summary>

* A brand writes the loyalty tier of the wallet account as a tag on the Shopify customer.

</details>

## Registration

| Key                                 | Slot file                   | Methods (required in **bold**)   |
| ----------------------------------- | --------------------------- | -------------------------------- |
| `extensions.shopify.customerMapper` | `shopify.customerMapper.js` | `MapFromShopify`, `MapToShopify` |

The file sits in `server/scripts/`. The slot is the **Customer mapper** script of the **Advanced** tab of the Shopify connector, read and written with `GET` and `PUT /api/{tenantId}/admin/extensions/shopify/scripts`. When no script is registered, the default mapping applies.

The mapper is used through the `shopify` entry of `customerProviders` in `server/account.yml` and the `shopify` step of a registration flow, as set up on the connector page. The Shopify app needs the scopes `read_customers` and `write_customers`.

```js
export default function (context) {
  context.register('extensions.shopify.customerMapper', {
    MapFromShopify: (customer, account) => {},
    MapToShopify: (account, customer) => {}
  });
}
```

## When it runs

`MapFromShopify` runs when the Shopify customer provider fills the account, after the default mapping (for example, `country` comes from `DefaultAddress.CountryCode`). `MapToShopify` runs before the Shopify customer is created or updated by the `shopify` registration flow step.

## Handlers

Both methods are optional: a script can register one direction only.

| Method           | Parameters            | Returns | Required | Sync or async |
| ---------------- | --------------------- | ------- | -------- | ------------- |
| `MapFromShopify` | `customer`, `account` | nothing | Optional | Synchronous   |
| `MapToShopify`   | `account`, `customer` | nothing | Optional | Synchronous   |

`customer` is the Shopify customer, with PascalCase .NET members (`customer.Email`, `customer.Tags`, `customer.DefaultAddress`). `account` is the flat wallet account (see [Data objects](https://docs.thewalletcrew.io/developers-guides/scripting/data-objects.md)). Both methods change their arguments in place. An `async` handler is not awaited, so changes made after an `await` are lost. A throw is not caught and fails the customer read or the `shopify` registration step.

In `MapToShopify`, `customer` is built from the account and is not read from Shopify first: it carries only the values the connector sets, then the connector creates or updates the Shopify customer with it. The default write mapping is:

| Account key                             | Shopify customer member                                                                                           |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `email`                                 | `Email`                                                                                                           |
| `phoneNumber`                           | `Phone`                                                                                                           |
| `firstName`, `lastName`                 | `FirstName`, `LastName`                                                                                           |
| `address`, `zipCode`, `city`, `country` | the default address (`Address1`, `Zip`, `City`, `CountryCode`), when one of `address`, `zipCode` or `city` is set |
| `consents_email`                        | `EmailMarketingConsent` (subscribed or unsubscribed), when the account has an email                               |
| `consents_sms`                          | `SmsMarketingConsent` (subscribed or unsubscribed), when the account has a phone number                           |
| `neo.src`                               | `Tags`                                                                                                            |

The prefix `neostore` is the platform's former name and is kept in technical identifiers.

## Errors and edge cases

* **No script registered**: the default mapping applies.
* **A method is missing**: it is skipped, as both are optional.
* **A member is misspelled**: it is ignored without an error. Use the PascalCase names of the Shopify customer.
* **A script throws**: the error reaches the operation that called it.

## Example

The script copies the country code of the default address into a custom key of the account, and adds the tier to the tags. `Tags` is a comma-separated string; on write it holds only the `neo.src` value the connector set, never the tags already stored in Shopify. The tier key `tier` is a placeholder.

```js
function mapFromShopify(customer, account) {
  const countryCode = customer?.DefaultAddress?.CountryCode;
  if (countryCode) {
    account['shopify.countryCode'] = countryCode;
  }
}

function mapToShopify(account, customer) {
  const tier = account['tier'];
  if (!tier) {
    return;
  }
  const tags = customer.Tags ? [customer.Tags] : [];
  tags.push(`tier-${tier}`);
  customer.Tags = tags.join(', ');
}

export default function (context) {
  context.register('extensions.shopify.customerMapper', {
    MapFromShopify: mapFromShopify,
    MapToShopify: mapToShopify
  });
}
```

## Common pitfalls

* The `shopify` step is listed after the `pass` step in the flow, so the customer is created too late.
* The Shopify app lacks the `write_customers` scope, so the update fails.
* The script expects `customer` to hold the values stored in Shopify: in `MapToShopify` it holds only what the connector built from the account.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/extensions/shopify.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
