Skip to main content

CRM App

Saleor version required: 3.10Repository: GitHub

Overview​

CRM is a Saleor App that allows providing customer data to external services. Here are the currently available providers:

There are two main features CRM App provides:

  • Initial indexing of existing Saleor customers and sending them to the provider contact list
  • Synchronizing new customers between Saleor and the provider
caution

To successfully configure the CRM App, you must:

  • Have a Mailchimp account
  • Have a Saleor user with MANAGE_APPS permission

Installation​

The App can be installed from Saleor App Store. To install the App, you must have MANAGE_USERS and MANAGE_APPS permissions.

Configuration​

The App is configured per provider. You can configure multiple providers - the App will work with at least one provider set up.

Mailchimp​

Authorization​

The app uses Mailchimp OAuth flow, meaning it will ask you to log in with Mailchimp and connect the App with your Saleor account. You can always disconnect the App from the Mailchimp dashboard.

After successful authorization, the App will store a token used to connect with a Mailchimp API.

You can disconnect your Mailchimp account and "forget" the token from App/Saleor from the App configuration screen. The token will be removed and you will have to connect with Mailchimp again to continue using it.

To permanently disconnect the App, you have to visit the Mailchimp dashboard.

Customer creation webhook​

The App allows sending new or updated customers to Mailchimp via a dedicated Saleor webhook. By default, this feature is disabled. When you enable it, you have to select what Mailchimp audience list contact should be synchronized to (likely you have only one).

The App will set a customer in Mailchimp when a Saleor customer is created (CUSTOMER_CREATED event) or updated (CUSTOMER_UPDATED event).

Customers bulk sync​

If you install the App and already have previously created customers, you would likely want to perform an initial indexing of customers and send them to the provider.

You can do that from the App.

caution

Customer synchronization works on the frontend side, which means the App must remain open during this operation. In large shops, this operation can take a few seconds.

Mailchimp tags and fields mapping​

The contacts created by the App will have the "Non-subscribed" status (transactional in the API).

Built-in fields​

The App will automatically map the customer email (mandatory), first (FNAME) and last (LNAME) names (optional).

Tags​

Your campaigns likely rely on segments based on custom fields and tags. For example, only customers who agreed on marketing emails, should receive specific campaigns.

One way to model this with Saleor is using PrivateMetadata for each customer.

CRM App has built-in Metadata mapping, allowing you to push tag values to the Metadata field and the App will handle the rest.

The App will parse Metadata items with the mailchimp_tags key and extract tags that will be added to each contact. These tags can be used to create segments and bulk-modify customers in Mailchimp.

Tags must be an array of strings, for example: ["tag 1", "tag 2"].

An example query that can be implemented in the storefront after the user agrees to the marketing campaigns:

mutation SetMailchimpTags($customerID: ID!) {
  updatePrivateMetadata(
    id: $customerID
    input: {
      key: "mailchimp_tags"
      value: "[\"general_marketing\", \"new_products_updates\"]"
    }
  ) {
    errors {
      message
    }
  }
}

Development​

To run the CRM App locally:

  1. Follow the Running Saleor Apps locally article.
  2. Go to the app directory.
  3. Copy the .env.example file to .env.
info

CRM is a Next.js application. If you want to learn more about setting environment variables in Next.js, head over to the documentation.

MAILCHIMP_CLIENT_ID and MAILCHIMP_CLIENT_SECRET can be obtained in the Mailchimp Dashboard when a new OAuth integration is created.

SECRET_KEY (required)

A randomly generated key that encrypts metadata stored in Saleor. At least eight characters long.

APL (optional)

Name of the chosen implementation of the Authentication Persistence Layer.

When no value is provided, FileAPL is used by default. See saleor-app.ts in the app directory to see supported APLs.

APP_LOG_LEVEL (optional)

Logging level based on which the app will decide on what messages to log.

The possible values are: trace, debug, info, warn, error, fatal, and silent. The default value is silent which means no logs will be printed.

You can read more about our logger in its documentation.

ALLOWED_DOMAIN_PATTERN (optional)

A regex pattern that prohibits the app from being installed on a Saleor instance that does not match the pattern. If not set, all installations will be allowed.