medusa-store/docs/content/development/events/events-list.md

description

description
Learn about the available events and their data payloads in Medusa. Events can be used to perform an action when the events are triggered.

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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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.

Event Name	Description	Event 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 Name	Description	Event 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.

Event Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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 Name	Description	Event 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

• Events architecture overview
• Use services in subscribers
• Create a notification provider