Skip to main content

Events Reference

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
}

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
}

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
}

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
}

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
}

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
}

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
}

Currency Events​

This section holds all events related to currencies.

Event NameDescriptionEvent Data Payload

currency.updated

Triggered when a currency is updated.

Object of the following format:

{
  code // string 3 character ISO code of the updated currency.
}

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
}
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

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.

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
}

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
}

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
}

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
}

order.orders_claimed

Triggered when an order is claimed.

Object of the following format:

{
  id, //string ID of order
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

Order Edit Events​

This section holds all events related to order edits.

Event NameDescriptionEvent Data Payload

order-edit.created

Triggered when a order edit is created.

Object of the following format:

{
  id, //string ID of order edit
}

order-edit.updated

Triggered when an order edit is updated.

Object of the following format:

{
  id, //string ID of order edit
}

order-edit.canceled

Triggered when an order edit is canceled.

Object of the following format:

{
  id, //string ID of order edit
}

order-edit.declined

Triggered when an order edit is declined.

Object of the following format:

{
  id, //string ID of order edit
}

order-edit.requested

Triggered when an order edit is requested.

Object of the following format:

{
  id // string ID of order edit
}

order-edit.confirmed

Triggered when an order edit is confirmed.

Object of the following format:

{
  id, //string ID of order edit
}

Order Edit Item Changes Events​

This section holds all events related to order edit item changes.

Event NameDescriptionEvent Data Payload

order-edit-item-change.CREATED

Triggered when an order edit item change is created.

{
  id // string ID of item change
}

order-edit-item-change.DELETED

Triggered when an order edit item change is deleted.

{
  id // string ID of item change
}

Payment Events​

This section holds all events related to payment.

Event NameDescriptionEvent Data Payload

payment.created

Triggered when a payment is created.

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

payment.updated

Triggered when a payment is updated.

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

payment.payment_captured

Triggered when a payment is captured.

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

payment.payment_capture_failed

Triggered when the capturing of a payment fails.

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

In addition, an error object is passed within the same object as the Payment provider:

{
  id, //string ID of payment
  //... other payment fields
  error: {
    name, //string
    nessage, //string
    stack, //(optional) string
  }
}

payment.payment_refund_created

Triggered when a refund of a payment is created.

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

payment.payment_refund_failed

Triggered when a payment's refund fails.

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

Payment Collection Events​

This section holds all events related to payment collections.

Event NameDescriptionEvent Data Payload

payment-collection.created

Triggered when a payment collection is created.

The entire payment collection passed as an object. You can refer to the Payment Collection entity for an idea of what fields to expect.

payment-collection.updated

Triggered when a payment collection is update.

The entire payment collection passed as an object. You can refer to the Payment Collection entity for an idea of what fields to expect.

payment-collection.deleted

Triggered when a payment collection is deleted.

The entire payment collection passed as an object. You can refer to the Payment Collection entity for an idea of what fields to expect.

payment-collection.payment_authorized

Triggered when a payment collection is either marked authorized or its payment session is authorized.

The entire payment collection passed as an object. You can refer to the Payment Collection entity for an idea of what fields to expect.

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 Category Events​

This section holds all events related to product categories.

Event NameDescriptionEvent Data Payload

product-category.created

Triggered when a product category is created.

Object of the following format:

{
  id, // string ID of category
}

product-category.updated

Triggered when a product category is updated.

Object of the following format:

{
  id, // string ID of category
}

product-category.deleted

Triggered when a product category is deleted.

Object of the following format:

{
  id, // string ID of category
}

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
}

Publishable API Key Events​

This section holds all events related to publishable API keys.

As of Medusa v1.6.3, Publishable API Keys are available but guarded by a feature flag. To use Publishable API Keys either:

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

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

Event NameDescriptionEvent Data Payload

publishable_api_key.created

Triggered when a publishable API key is created.

Object of the following format:

{
  id // string ID of publishable API key
}

publishable_api_key.revoked

Triggered when a publishable API key is revoked.

Object of the following format:

{
  id // string ID of publishable API key
}

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.

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

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
}

Token Events​

This section holds all events related to tokens.

Event NameDescriptionEvent Data Payload

order-update-token.created

Triggered when a customer requests to claim an order and a token is created.

Object of the following format:

{
  old_email, //string email of order
  new_customer_id, //string ID of customer
  orders, //array of string IDs of orders
  token, //string token used for verification
}

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
}

See Also​