Skip to main content

Events List

This document details all events in Medusa, when they are triggered, and what data your handler method will receive when the event is triggered.

Prerequisites

It is assumed you’re already familiar with Subscribers in Medusa and how to listen to events. You can then use the name of events from this documentation in your subscriber to listen to events.

Legend

Events in this document are listed under the entity they’re associated with. They’re listed in a table of three columns:

  1. Event Name: The name you use to subscribe a handler for the event.
  2. Description: When this event is triggered.
  3. Event Data Payload: The data your handler receives as a parameter.

Batch Jobs Events

This section holds all events related to batch jobs.

Event NameDescriptionEvent Data Payload

batch.created

Triggered when a batch job is created.Object of the following format:
{
id //string ID of batch job
}

batch.updated

Triggered when a batch job is updated.Object of the following format:
{
id //string ID of batch job
}

batch.canceled

Triggered when a batch job is canceled.Object of the following format:
{
id //string ID of batch job
}

batch.pre_processed

Triggered after the preProcessBatchJob of a batch job stategy is done executing.

Object of the following format:
{
id //string ID of batch job
}

batch.confirmed

Triggered after the batch job is done pre-processing and the batch job is not in dry-run mode.

Object of the following format:
{
id //string ID of batch job
}

batch.processing

Triggered when a batch job starts processing after it's confirmed.Object of the following format:
{
id //string ID of batch job
}

batch.completed

Triggered when a batch job is done processing and is completed.Object of the following format:
{
id //string ID of batch job
}

batch.failed

Triggered when an error occurs while running a batch job and the batch job fails.Object of the following format:
{
id //string ID of batch job
}

Cart Events

This section holds all events related to a cart.

Event NameDescriptionEvent Data Payload

cart.customer_updated

Triggered when a cart is associated with a different email than it was already associated with, or if a customer logs in after adding items to their cart as a guest.The cart ID passed as a string parameter.

cart.created

Triggered when a cart is created.Object of the following format:
{
id //string ID of cart
}

cart.updated

Triggered when a cart and data associated with it (payment sessions, shipping methods, user details, etc…) are updated.

An object with at least the ID of the cart, however, in most cases the entire cart model is available. You can refer to the Cart entity for an idea of what fields to expect.

Claim Events

This section holds all events related to claims.

Event NameDescriptionEvent Data Payload

claim.created

Triggered when a claim is created.

Object of the following format:

{
id, //string ID of claim
no_notification //boolean indicating whether a notification should be sent or not
}

claim.updated

Triggered when a claim is updated.

Object of the following format:

{
id, //string ID of claim
no_notification //boolean indicating whether a notification should be sent or not
}

claim.canceled

Triggered when a claim is canceled.

Object of the following format:

{
id, //string ID of claim
no_notification //boolean indicating whether a notification should be sent or not
}

claim.fulfillment_created

Triggered when fulfillment is created for a claim.

Object of the following format:

{
id, //string ID of claim
fulfillment_id, //string ID of the fulfillment created
no_notification //boolean indicating whether a notification should be sent or not
}

claim.shipment_created

Triggered when a claim fulfillment is set as “shipped”.

Object of the following format:

{
id, //string ID of claim
fulfillment_id, //string ID of the fulfillment created
no_notification //boolean indicating whether a notification should be sent or not
}

claim.refund_processed

Triggered when a claim of type “refunded” has been refunded.

Object of the following format:

{
id, //string ID of claim
no_notification //boolean indicating whether a notification should be sent or not
}

Claim Item Events

This section holds all events related to claim items.

Event NameDescriptionEvent Data Payload

claim_item.created

Triggered when claim items are created and associated with a claim. This happens during the creation of claims.

Object of the following format:

{
id //string ID of claim item
}

claim_item.updated

Triggered when a claim item is updated. This happens when a claim is updated.

Object of the following format:

{
id //string ID of claim item
}

claim_item.canceled

Triggered when a claim is canceled.

Object of the following format:

{
id //string ID of claim item
}

Customer Events

This section holds all events related to customers.

Event NameDescriptionEvent Data Payload

customer.created

Triggered when a customer is created.

The entire customer passed as an object. You can refer to the Customer entity for an idea of what fields to expect.

customer.updated

Triggered when a customer is updated including their information or password, or when a customer account is created that is associated with an existing email (for example, if a customer placed an order with their email as a guest, then created an account with that email).

The entire customer passed as an object. You can refer to the Customer entity for an idea of what fields to expect.

customer.password_reset

Triggered when a customer requests to reset their password.

Object of the following format:

{
id, //string ID of customer
email, //string email of the customer
first_name, //string first name of the customer
last_name, //string last name of the customer
token //string reset password token
}

Draft Order Events

This section holds all events related to draft orders.

Event NameDescriptionEvent Data Payload

draft_order.created

Triggered when a draft order is created.

Object of the following format:

{
id //string ID of draft order
}

draft_order.updated

Triggered when a draft order and data associated with it (email, billing address, discount, etc…) are updated.

Object of the following format:

{
id //string ID of draft order
}

Gift Card Events

This section holds all events related to gift cards.

Event NameDescriptionEvent Data Payload

gift_card.created

Triggered when a gift card is created.

Object of the following format:

{
id //string ID of gift card
}

Invite Events

This section holds all events related to invites.

Event NameDescriptionEvent Data Payload

invite.created

Triggered when an invite is created for a user to join the admin team.

Object of the following format:

{
id //string ID of invite
token, //string token generated to validate the invited user
user_email //string email of invited user
}

Note Events

This section holds all events related to notes.

Event NameDescriptionEvent Data Payload

note.created

Triggered when a note is created.

Object of the following format:

{
id //string ID of note
}

note.updated

Triggered when a note is updated.

Object of the following format:

{
id //string ID of note
}

note.deleted

Triggered when a note is deleted.

Object of the following format:

{
id //string ID of note
}

App Authentication Events

This section holds all events related to app authentications.

note

Event names of app authentication are scoped specifically towards each application. When listening to these events, you must replace <APP> with the name of the application you’re targeting.

Event NameDescriptionEvent Data Payload

oauth.token_generated.<APP>

Triggered when a token is generated for an application.

The returned data from the method generateToken in the auth handler service of the application.

oauth.token_refreshed.<APP>

Triggered when the token of an application is refreshed.

The returned data from the method refreshToken in the auth handler service of the application.

Order Events

This section holds all events related to orders.

Event NameDescriptionEvent Data Payload

order.placed

Triggered when a new order is placed.

Object of the following format:

{
id, //string ID of order
no_notification //boolean indicating whether a notification should be sent or not
}

order.updated

Triggered when an order and data associated with it (shipping method, shipping address, etc…) are updated.

Object of the following format:

{
id, //string ID of order
no_notification //(optional) boolean indicating whether a notification should be sent or not
}

order.canceled

Triggered when an order is canceled.

Object of the following format:

{
id, //string ID of order
no_notification //boolean indicating whether a notification should be sent or not
}

order.completed

Triggered when an order is completed.

Object of the following format:

{
id, //string ID of order
no_notification //boolean indicating whether a notification should be sent or not
}

order.gift_card_created

Triggered when a gift card in an order is created.

Object of the following format:

{
id //string ID of order
}

order.payment_captured

Triggered when the payment of an order is captured.

Object of the following format:

{
id, //string ID of order
no_notification //boolean indicating whether a notification should be sent or not
}

order.payment_capture_failed

Triggered when capturing the payment of an order fails.

Object of the following format:

{
id, //string ID of order
payment_id, //string ID of Payment
error, //string error message
no_notification //boolean indicating whether a notification should be sent or not
}

order.fulfillment_created

Triggered when fulfillment is created for an order.

Object of the following format:

{
id, //string ID of order
fulfillment_id, //string ID of fulfillment
no_notification //boolean indicating whether a notification should be sent or not
}

order.shipment_created

Triggered when a shipment is created for fulfillment and the fulfillment is registered as “shipped”.

Object of the following format:

{
id, //string ID of order
fulfillment_id, //string ID of fulfillment
no_notification //boolean indicating whether a notification should be sent or not
}

order.fulfillment_canceled

Triggered when fulfillment of an order is canceled.

Object of the following format:

{
id, //string ID of order
fulfillment_id, //string ID of fulfillment
no_notification //boolean indicating whether a notification should be sent or not
}

order.return_requested

Triggered when a return of an order is requested.

Object of the following format:

{
id, //string ID of order
return_id, //string ID of return
no_notification //(optional) boolean indicating whether a notification should be sent or not
}

order.items_returned

Triggered when the items of an order have been returned and the order has been registered as “returned”.

Object of the following format:

{
id, //string ID of order
return_id, //string ID of return
no_notification //boolean indicating whether a notification should be sent or not
}

order.return_action_required

Triggered when the order is being registered as “returned” but there are additional actions required related to refunding the payment.

Object of the following format:

{
id, //string ID of order
return_id, //string ID of return
no_notification //boolean indicating whether a notification should be sent or not
}

order.refund_created

Triggered when the order’s payment is refunded.

Object of the following format:

{
id, //string ID of order
refund_id, //string ID of refund
no_notification //boolean indicating whether a notification should be sent or not
}

order.refund_failed

Triggered when the refund of the order’s payment fails.

Object of the following format:

{
id, //string ID of order
}

order.swap_created

Triggered when a swap for an order is created.

Object of the following format:

{
id, //string ID of order
}

Product Events

This section holds all events related to products.

Event NameDescriptionEvent Data Payload

product.created

Triggered when a product is created.

Object of the following format:

{
id //string ID of product
}

product.updated

Triggered when a product and data associated with it (options, variant orders, etc…) is updated.

The entire product passed as an object. You can refer to the Product entity for an idea of what fields to expect.

In one case, when the /admin/products/{id} endpoint is used to update the product, the payload is an object of the following format:

{
id, //id of product
fields //an array of field names that were updated
}

product.deleted

Triggered when a product is deleted.

Object of the following format:

{
id //string ID of product
}

Product Variant Events

This section holds all events related to product variants.

Event NameDescriptionEvent Data Payload

product-variant.created

Triggered when a product variant is created.

Object of the following format:

{
id, //string ID of variant
product_id //string ID of product
}

product-variant.updated

Triggered when a product variant is updated.

Object of the following format:

{
id, //string ID of variant
product_id, //string ID of product
fields //array of names of updated fields
}

product-variant.deleted

Triggered when a product variant is deleted.

Object of the following format:

{
id, //string ID of variant
product_id, //string ID of product
metadata //object of the `metadata` field of the variant
}

Region Events

This section holds all events related to regions.

Event NameDescriptionEvent Data Payload

region.created

Triggered when a region is created.

Object of the following format:

{
id //string ID of region
}

region.updated

Triggered when a region or data associated with it (countries, fulfillment providers, etc…) are updated.

Object of the following format:

{
id, //string ID of region
fields //array of names of updated fields
}

region.deleted

Triggered when a region is deleted.

Object of the following format:

{
id //string ID of region
}

Sales Channel Events

This section holds all events related to sales channels.

note

As of Medusa v1.3.5, Sales Channels are available but guarded by a feature flag. To use Sales Channels either:

  1. Enable the MEDUSA_FF_SALES_CHANNELS environment variable;
  2. Or enable the sales_channels key in the Medusa server's settings.

You can learn more about enabling it in the feature flags documentation.

Event NameDescriptionEvent Data Payload

sales_channel.created

Triggered when a sales channel is created.

Object of the following format:

{
id //string ID of sales channel
}

sales_channel.updated

Triggered when a sales channel is updated

Object of the following format:

{
id, //string ID of sales channel
}

sales_channel.deleted

Triggered when a sales channel is deleted.

Object of the following format:

{
id //string ID of sales channel
}

Swap Events

This section holds all events related to swaps.

Event NameDescriptionEvent Data Payload

swap.created

Triggered when a swap is created.

Object of the following format:

{
id, //string ID of swap
no_notification //boolean indicating whether a notification should be sent or not
}

swap.received

Triggered when a swap is registered as received.

Object of the following format:

{
id, //string ID of swap
order_id, //string ID of order
no_notification //boolean indicating whether a notification should be sent or not
}

swap.fulfillment_created

Triggered when fulfillment is created for a swap.

Object of the following format:

{
id, //string ID of swap
fulfillment_id, //string ID of fulfillment
no_notification //boolean indicating whether a notification should be sent or not
}

swap.shipment_created

Triggered when a shipment is created for a swap and the fulfillment associated with it is set as “shipped”.

Object of the following format:

{
id, //string ID of swap
fulfillment_id, //string ID of fulfillment
no_notification //boolean indicating whether a notification should be sent or not
}

swap.payment_completed

Triggered when payment is completed for a swap which happens when the cart associated with the swap is registered as completed.

Object of the following format:

{
id, //string ID of swap
no_notification //boolean indicating whether a notification should be sent or not
}

swap.payment_captured

Triggered when the payment is captured for a swap.

Object of the following format:

{
id, //string ID of swap
no_notification //boolean indicating whether a notification should be sent or not
}

swap.payment_capture_failed

Triggered when the capturing of the payment of a swap fails.

Object of the following format:

{
id, //string ID of swap
no_notification //boolean indicating whether a notification should be sent or not
}

swap.refund_processed

Triggered when a swap’s amount difference is processed and refunded.

Object of the following format:

{
id, //string ID of swap
no_notification //boolean indicating whether a notification should be sent or not
}

swap.process_refund_failed

Triggered when processing and refunding a swap’s amount difference fails.

Object of the following format:

{
id, //string ID of swap
no_notification //boolean indicating whether a notification should be sent or not
}

User Events

This section holds all events related to users.

Event NameDescriptionEvent Data Payload

user.created

Triggered when a user is created.

Object of the following format:

{
id //string ID of user
}

user.updated

Triggered when a user is updated.

Object of the following format:

{
id //string ID of user
}

user.password_reset

Triggered when a user requests to reset their password.

Object of the following format:

{
email, //string email of user requesting to reset their password
token //token create to reset the password
}

user.deleted

Triggered when a user is deleted.

Object of the following format:

{
id //string ID of user
}

What’s Next 🚀