# 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](create-subscriber.md). 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: ```js { id //string ID of batch job } ```
`batch.updated` Triggered when a batch job is updated. Object of the following format: ```js { id //string ID of batch job } ```
`batch.canceled` Triggered when a batch job is canceled. Object of the following format: ```js { 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: ```js { 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: ```js { id //string ID of batch job } ```
`batch.processing` Triggered when a batch job starts processing after it's confirmed. Object of the following format: ```js { id //string ID of batch job } ```
`batch.completed` Triggered when a batch job is done processing and is completed. Object of the following format: ```js { 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: ```js { 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: ```js { 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](https://github.com/medusajs/medusa/blob/master/packages/medusa/src/models/cart.ts) 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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 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: ```js { 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: ```js { id //string ID of claim item } ```
`claim_item.canceled` Triggered when a claim is canceled. Object of the following format: ```js { id //string ID of claim item } ```
## 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](https://github.com/medusajs/medusa/blob/master/packages/medusa/src/models/customer.ts) 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](https://github.com/medusajs/medusa/blob/master/packages/medusa/src/models/customer.ts) 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { id //string ID of note } ```
`note.updated` Triggered when a note is updated. Object of the following format: ```js { id //string ID of note } ```
`note.deleted` Triggered when a note is deleted. Object of the following format: ```js { 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 `` with the name of the application you’re targeting. :::
Event Name Description Event Data Payload
`oauth.token_generated.` 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.` 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { id //string ID of order } ```
`order.payment_captured` Triggered when the payment of an order is captured. Object of the following format: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { id, //string ID of order } ```
`order.swap_created` Triggered when a swap for an order is created. Object of the following format: ```js { id, //string ID of order } ```
## 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: ```js { 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](https://github.com/medusajs/medusa/blob/master/packages/medusa/src/models/product.ts) 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: ```js { 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: ```js { id //string ID of product } ```
## 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: ```js { 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: ```js { 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: ```js { 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 Name Description Event Data Payload
`region.created` Triggered when a region is created. Object of the following format: ```js { 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: ```js { 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: ```js { 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](../feature-flags/toggle.md) documentation. :::
Event Name Description Event Data Payload
`sales_channel.created` Triggered when a sales channel is created. Object of the following format: ```js { id //string ID of sales channel } ```
`sales_channel.updated` Triggered when a sales channel is updated Object of the following format: ```js { id, //string ID of sales channel } ```
`sales_channel.deleted` Triggered when a sales channel is deleted. Object of the following format: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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: ```js { 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 Name Description Event Data Payload
`user.created` Triggered when a user is created. Object of the following format: ```js { id //string ID of user } ```
`user.updated` Triggered when a user is updated. Object of the following format: ```js { id //string ID of user } ```
`user.password_reset` Triggered when a user requests to reset their password. Object of the following format: ```js { 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: ```js { id //string ID of user } ```
## What’s Next 🚀 - Learn how you can [use services in subscribers](create-subscriber.md#using-services-in-subscribers). - Learn how to [create notifications](../notification/overview.md) in Medusa.