Built by

luluhoc

Category

Other

Version

2.0.56

Last updated

May 13, 2024, 12:00:24 PM2 months ago

Medusa Abandoned Cart Plugin

Still in beta proceed with caution

v2.0.0 - Contains breaking changes. Please read the documentation carefully

You can now send emails with other providers and schedule the task to send emails. Remember to run migrations after adding the plugin to the Copy to clipboardmedusa-config.js file
This plugin adds abandoned cart functionality to Medusa. It allows you to send emails to customers who have abandoned their carts. The plugin uses SendGrid to send the emails. The plugin is written in Typescript.
I strongly recommend using this plugin in combination with the Medusa Plugin SendGrid Typescript to get type safety and autocompletion for the SendGrid API. You can also use the Medusa Plugin SendGrid

Image

Medusa Website | Medusa Repository

Features

  • Send emails to customers who have abandoned their carts manualy.
  • Get a list of abandoned carts in Admin.
  • Send emails with other provider (new)
  • Send emails with scheduled task (new) cron job runs every 5 minutes.

Prerequisites

How to Install

1. Run the following command in the directory of the Medusa backend

  yarn add medusa-plugin-abandoned-cart
  npm install medusa-plugin-abandoned-cart

2. Set the following environment variable in Copy to clipboard.env

  SENDGRID_API_KEY=<API_KEY>
  SENDGRID_FROM=<SEND_FROM_EMAIL>
  # IDs for different email templates
  SENDGRID_ABANDONED_CART_TEMPLATE=<ORDER_PLACED_TEMPLATE_ID> # example

3. In Copy to clipboardmedusa-config.js add the following at the end of the Copy to clipboardplugins array

const plugins = [
  // ...,
  {
    resolve: `medusa-plugin-abandoned-cart`,
    /** @type {import('medusa-plugin-abandoned-cart').PluginOptions} */
    options: {
      sendgridEnabled: true,
      from: process.env.SENDGRID_FROM,
      enableUI: true,
      subject: "You have something in your cart",
      templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
      days_to_track: 7,
      set_as_completed_if_overdue: true,
      max_overdue: "2h",
      localization: {
        fr: {
          subject: "Vous avez quelque chose dans votre panier",
          templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_FR,
        },
        pl: {
          subject: "Masz coś w koszyku",
          templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_PL,
        },
        en: {
          subject: "You have something in your cart",
          templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
        },
      },
      intervals: [
        {
          interval: "1h",
          subject: "You have something in your cart",
          templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
          localization: {
            fr: {
              subject: "Vous avez quelque chose dans votre panier",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_FR,
            },
            pl: {
              subject: "Masz coś w koszyku",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_PL,
            },
            en: {
              subject: "You have something in your cart",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
            },
          },
        },
        {
          interval: "1d",
          subject: "You have something in your cart",
          templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
          localization: {
            fr: {
              subject: "Vous avez quelque chose dans votre panier",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_FR,
            },
            pl: {
              subject: "Masz coś w koszyku",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_PL,
            },
            en: {
              subject: "You have something in your cart",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
            },
          },
        },
        {
          interval: "5d",
          subject: "You have something in your cart",
          templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
          localization: {
            fr: {
              subject: "Vous avez quelque chose dans votre panier",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_FR,
            },
            pl: {
              subject: "Masz coś w koszyku",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE_PL,
            },
            en: {
              subject: "You have something in your cart",
              templateId: process.env.SENDGRID_ABANDONED_CART_TEMPLATE,
            },
          },
        },
      ],
    },
  },
];
  export interface BasePluginOptions {
  /* enable sendgrid */
  sendgridEnabled: boolean
  /* email from which you will be sending */
  from: { name?: string; email: string } | string
  /* template id from sendgrid */
  templateId: string
  /* header line of the email optional */
  header?: string
  /* number of days to track */
  days_to_track?: number
  /* subject of the email optional */
  subject?: string
  localization?: {
    [key: string]: {
      subject?: string
      header?: string
      templateId: string
    };
  }
}


export interface IntervalOptions {
  /* interval example string "1d", "1h", "30m" 
  check parse-duration package for more examples */
  interval: string | number
  /* subject of the email optional */
  subject?: string
  /* template id from sendgrid */
  templateId?: string
  localization?: {
    [key: string]: {
      subject?: string
      header?: string
      templateId: string
    };
  }


}


export interface AutomatedAbandonedCart extends BasePluginOptions {
  /* intervals */
  intervals: Array<IntervalOptions>,
  /* max overdue @default "2h"*/
  max_overdue: string
  /* set as completed if overdue */
  set_as_completed_if_overdue: boolean
}


export interface ManualAbandonedCart extends BasePluginOptions {
  localization: {
    [key: string]: {
      subject?: string
      header?: string
      templateId: string
    };
  }
}
Remember to run migrations after adding the plugin to the `medusa-config.js` file

4. The Sendgrid Template receives the following

export type NewLineItem = Omit<LineItem, "beforeUpdate" | "afterUpdateOrLoad"> & {
  // human readable price with currency code
  price: string
}


// The cart object is transformed to this format before sending the email
export interface TransformedCart {
  id: string;
  email: string;
  items: NewLineItem[];
  cart_context: Record<string, unknown>;
  first_name: string;
  last_name: string;
  totalPrice: number;
  created_at: Date;
  currency: string;
  region: string;
  country_code: string;
  region_name: string;
  abandoned_count?: number;
  abandoned_lastdate?: Date;
  abandoned_last_interval?: number;
  abandoned_completed_at?: Date;
}

5. When an abandoned cart email is sent, the plugin emits the Copy to clipboardcart.send-abandoned-email event

You can listen to this event in your plugin to perform additional actions with your custom notification provider or perform extra actions when using Sendgrid.
  • The Event is sent one time when the button is pressed in the Admin UI.
  • The Event gets the following payload:
{
  id: string; // cart id
}
Check medusa docs https://docs.medusajs.com/development/events/create-subscriber

Example

import { 
  ProductService,
  type SubscriberConfig, 
  type SubscriberArgs, 
} from "@medusajs/medusa"
import { EntityManager } from "typeorm";
import { MedusaError } from 'medusa-core-utils';
import { TransformedCart } from "medusa-abandoned-cart-plugin";
import SendGridService from "medusa-plugin-sendgrid-typescript/dist/services/sendgrid";


export default async function abandonedEmailHandler({ 
  data, eventName, container, pluginOptions, 
}: SubscriberArgs<Record<string, any>>) {
  const manager: EntityManager = container.resolve("manager")
  const cartRepo = manager.getRepository(Cart)
  const abandonedCartService: AbandonedCartService = container.resolve("abandonedCartService")
  const sendGridService: SendGridService = container.resolve("sendGridService")


  const { id, interval } = data


  const notNullCartsPromise = await cartRepo.findOne({
    where: {
      id,
    },
    order: {
      created_at: "DESC",
    },
    select: ["id", "email", "created_at", "region", "context", "abandoned_count"],
    relations: ["items", "region", "shipping_address"],
  })


  if (!notNullCartsPromise) {
    throw new MedusaError("Not Found", "Cart not found")
  }
  // do something with the cart...


  // Transform the cart to the format needed for the email template this is mandatory depending on email template and provider
  const cart = abandonedCartService.transformCart(notNullCartsPromise) as TransformedCart


  const emailData = {
    to: cart.email,
    from: this.options_.from,
    templateId: "d-1234567890abcdef",
    dynamic_template_data: {
      ...cart,
    },
  }


  // Send email using sendgrid
  const sendGridPromise = this.sendGridService.sendEmail(emailData)


  // Update the cart to reflect that the email has been sent
  const repoPromise = cartRepo.update(cart.id, {
        abandoned_lastdate: new Date().toISOString(),
        abandoned_count: (notNullCartsPromise?.abandoned_count || 0) + 1,
        abandoned_last_interval: interval || undefined,
        abandoned_completed_at: interval && pluginOptions.intervals[pluginOptions.intervals.length - 1].interval === interval ? new Date().toISOString() : undefined,
      });


  await Promise.all([sendGridPromise, repoPromise])
  
}


export const config: SubscriberConfig = {
  event: "cart.send-abandoned-email",
  context: {
    subscriberId: "abandoned-email-handler",
  },
}

Build your own plugins

Develop your own plugins with our API to speed up your processes.

Make your plugin available via npm for it to be shared in our Plugin Library with the broader Medusa community.