# Event <p>Events are generated by some Shopify resources when certain actions are completed, such as the creation of an article, the fulfillment of an order, or the addition of a product. By requesting events, your app can know when certain actions have occurred in the shop.</p> <div class="note"> <h4>Note</h4> <p>The events returned by the Event resource should not be considered to be realtime. Events might not be created until a few seconds after the action occurs. In rare cases it can take up to a few minutes for some events to appear.</p> </div> {{ '/api/reference/event.png' | image }} <h2>Resources that can create events</h2> <p>Events are generated by the following resources: </p> <ul> <li><a href="#article-events">Articles</a></li> <li><a href="#blog-events">Blogs</a></li> <li><a href="#collection-events">Custom collections</a></li> <li><a href="#comment-events">Comments</a></li> <li><a href="#order-events">Orders</a></li> <li><a href="#page-events">Pages</a></li> <li><a href="#price-rule-events">Price rules</a></li> <li><a href="#product-events">Products</a></li> </ul> <h3 id="article-events">Article events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New article created: <code>article_url</code></td> <td>The article was created.</td> </tr> <tr> <td><code>destroy</code></td> <td><code>article_url</code> was destroyed.</td> <td>The article was deleted.</td> </tr> <tr> <td><code>published</code></td> <td><code>article_url</code> was published.</td> <td>The article was published.</td> </tr> <tr> <td><code>unpublished</code></td> <td><code>article_url</code> was unpublished.</td> <td>The article was unpublished.</td> </tr> <tr> <td><code>update</code></td> <td><code>article_url</code> was updated (but its published state was not changed).</td> <td>The article was updated.</td> </tr> </tbody> </table> <h3 id="blog-events">Blog events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New blog created: <code>new_blog_url</code></td> <td>The blog was created.</td> </tr> <tr> <td><code>destroy</code></td> <td><code>blog_name</code> was destroyed.</td> <td>The blog was deleted.</td> </tr> <tr> <td><code>update</code></td> <td><code>blog_name</code> was updated.</td> <td>The blog was updated.</td> </tr> </tbody> </table> <h3 id="collection-events">Collection events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New collection created: <code>collection_url</code></td> <td>The collection was created.</td> </tr> <tr> <td><code>destroy</code></td> <td><code>collection_url</code> was destroyed.</td> <td>The collection was deleted.</td> </tr> <tr> <td><code>published</code></td> <td><code>collection_url</code> was published.</td> <td>The collection was published.</td> </tr> <tr> <td><code>unpublished</code></td> <td><code>collection_url</code> was hidden.</td> <td>The collection was hidden.</td> </tr> <tr> <td><code>update</code></td> <td><code>collection_url</code> was updated.</td> <td>The collection was updated.</td> </tr> </tbody> </table> <h3 id="comment-events">Comment events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New comment for <code>article_url</code>: <code>comment_excerpt</code></td> <td>The comment was created.</td> </tr> </tbody> </table> <h3 id="order-events">Order events</h3> <p>Order events can be divided into the following categories:</p> <ul> <li><strong>Authorization</strong>: Includes whether the authorization succeeded, failed, or is pending.</li> <li><strong>Capture</strong>: Includes whether the capture succeeded, failed, or is pending.</li> <li><strong>Email</strong>: Includes confirmation or cancellation of the order, as well as shipping.</li> <li><strong>Fulfillment</strong>: Includes whether the fulfillment succeeded, failed, or is pending. Also includes cancellation, restocking, and fulfillment updates.</li> <li><strong>Order</strong>: Includess the placement, confirmation, closing, re-opening, and cancellation of the order.</li> <li><strong>Refund</strong>: Includes whether the refund succeeded, failed, or is pending.</li> <li><strong>Sale</strong>: Includes whether the sale succeeded, failed, or is pending.</li> <li><strong>Void</strong>: Includes whether the void succeeded, failed, or is pending.</li> </ul> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>authorization_failure</code></td> <td>The customer, unsuccessfully, tried to authorize: <code>money_amount</code></td> <td>Authorization failed. The funds cannot be captured.</td> </tr> <tr> <td><code>authorization_pending</code></td> <td>Authorization for <code>money_amount</code> is pending.</td> <td>Authorization failed. The funds cannot be captured.</td> </tr> <tr> <td><code>authorization_success</code></td> <td>The customer successfully authorized us to capture: <code>money_amount</code></td> <td>Authorization was successful and the funds are available for capture.</td> </tr> <tr> <td><code>cancelled</code></td> <td>Order was cancelled by <code>shop_staff_name</code>. </td> <td>The order was cancelled.</td> </tr> <tr> <td><code>capture_failure</code></td> <td>We failed to capture: <code>money_amount</code></td> <td>The capture failed. The funds cannot be transferred to the shop.</td> </tr> <tr> <td><code>capture_pending</code></td> <td>Capture for <code>money_amount</code> is pending.</td> <td>The capture is in process. The funds are not yet available to the shop.</td> </tr> <tr> <td><code>capture_success</code></td> <td>We successfully captured: <code>money_amount</code></td> <td>The capture was successful and the funds are now available to the shop.</td> </tr> <tr> <td><code>closed</code></td> <td>Order was closed.</td> <td>The order was closed.</td> </tr> <tr> <td><code>confirmed</code></td> <td>Received a new order: <code>order_number</code> by <code>customer_name</code>.</td> <td>The order was confirmed.</td> </tr> <tr> <td><code>fulfillment_cancelled</code></td> <td>We cancelled <code>number_of_line_items</code> from being fulfilled by the third party fulfillment service.</td> <td>Fulfillment for one or more of the line_items failed.</td> </tr> <tr> <td><code>fulfillment_pending</code></td> <td>We submitted <code>number_of_line_items</code> to the third party service.</td> <td>One or more of the line_items has been assigned to a third party service for fulfillment.</td> </tr> <tr> <td><code>fulfillment_success</code></td> <td>We successfully fulfilled line_items.</td> <td>Fulfillment was successful for one or more line_items.</td> </tr> <tr> <td><code>mail_sent</code></td> <td><code>message_type</code> email was sent to the customer.</td> <td>An email was sent to the customer.</td> </tr> <tr> <td><code>placed</code></td> <td>Order was placed.</td> <td>An order was placed by the customer.</td> </tr> <tr> <td><code>re_opened</code></td> <td>Order was re-opened.</td> <td>The order was re-opened.</td> </tr> <tr> <td><code>refund_failure</code></td> <td>We failed to refund <code>money_amount</code>.</td> <td>The refund failed. The funds are still with the shop.</td> </tr> <tr> <td><code>refund_pending</code></td> <td>Refund of <code>money_amount</code> is still pending.</td> <td>THe refund is in process. The funds are still with shop.</td> </tr> <tr> <td><code>refund_success</code></td> <td>We successfully refunded <code>money_amount</code>.</td> <td>The refund was successful. The funds have been transferred to the customer.</td> </tr> <tr> <td><code>restock_line_items</code></td> <td>We restocked <code>number_of_line_items</code>.</td> <td>One or more of the order's line items have been restocked.</td> </tr> <tr> <td><code>sale_failure</code></td> <td>The customer failed to pay <code>money_amount</code>.</td> <td>The sale failed. The funds are not available to the shop.</td> </tr> <tr> <td><code>sale_pending</code></td> <td>The <code>money_amount</code> is pending.</td> <td>The sale is in process. The funds are not yet available to the shop.</td> </tr> <tr> <td><code>sale_success</code></td> <td>We successfully captured <code>money_amount</code>.</td> <td>The sale was successful. The funds are now with the shop.</td> </tr> <tr> <td><code>update</code></td> <td><code>order_number</code> was updated.</td> <td>The order was updated.</td> </tr> <tr> <td><code>void_failure</code></td> <td>We failed to void the authorization.</td> <td>Voiding the authorization failed. The authorization is still valid.</td> </tr> <tr> <td><code>void_pending</code></td> <td>Authorization void is pending.</td> <td>Voiding the authorization is in process. The authorization is still valid.</td> </tr> <tr> <td><code>void_success</code></td> <td>We successfully voided the authorization.</td> <td>Voiding the authorization was successful. The authorization is no longer valid.</td> </tr> </tbody> </table> <h3 id="page-events">Page events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New page created: <code>page_url</code></td> <td>The page was created.</td> </tr> <tr> <td><code>destroy</code></td> <td><code>page_url</code> was destroyed.</td> <td>The page was deleted.</td> </tr> <tr> <td><code>published</code></td> <td><code>page_url</code> was published.</td> <td>The page was published.</td> </tr> <tr> <td><code>unpublished</code></td> <td><code>page_url</code> was hidden.</td> <td>The page was hidden.</td> </tr> <tr> <td><code>update</code></td> <td><code>page_url</code> was updated.</td> <td>The page was updated.</td> </tr> </tbody> </table> <h3 id="price-rule-events">Price rule events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New price rule created: <code>price_rule</code></td> <td>The price rule was created.</td> </tr> <tr> <td><code>destroy</code></td> <td><code>price_rule</code> was destroyed.</td> <td>The price rule was deleted.</td> </tr> <tr> <td><code>update</code></td> <td><code>price_rule</code> was updated.</td> <td>The price rule was updated.</td> </tr> </tbody> </table> <h3 id="product-events">Product events</h3> <table> <thead> <tr> <th>Verb</th> <th>Message</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>create</code></td> <td>New product created: <code>product_title</code></td> <td>The product was created.</td> </tr> <tr> <td><code>destroy</code></td> <td><code>product_name</code> was destroyed.</td> <td>The product was deleted.</td> </tr> <tr> <td><code>published</code></td> <td><code>product_title</code> was published.</td> <td>The product was published.</td> </tr> <tr> <td><code>unpublished</code></td> <td><code>product_title</code> was hidden.</td> <td>The product was hidden.</td> </tr> </tbody> </table> ## Resource Properties ### Event * arguments: Refers to a certain event and its resources. * Type: x-string * Example: ["IPod Nano - 8GB"] * body: A text field containing information about the event. * Type: x-string * Example: nil * created_at: The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>) when the event was created. * Type: x-string * Example: "2015-04-20T08:33:57-11:00" * id: The ID of the event. * Type: x-string * Example: 164748010 * description: A human readable description of the event. * Type: x-string * Example: "Received a new order" * path: A relative URL to the resource the event is for, if applicable. * Type: x-string * Example: "/admin/orders/406514653/transactions/#1145" * message: A human readable description of the event. Can contain some HTML formatting. * Type: x-string * Example: "Received new order" * subject_id: The ID of the resource that generated the event. * Type: x-string * Example: 406514653 * subject_type: <p>The type of the resource that generated the event. Valid values:</p> <ul> <li><code>Article</code></li> <li><code>Blog</code></li> <li><code>Collection</code></li> <li><code>Comment</code></li> <li><code>Order</code></li> <li><code>Page</code></li> <li><code>PriceRule</code></li> <li><code>Product</code></li> <li><code>ApiPermission</code></li> </ul> * Type: x-string * Example: "Order" * verb: The type of event that occurred. Different resources generate different types of event. See the <a href="#resources-that-can-create-events">Resources</a> section for a list of possible verbs. * Type: x-string * Example: "confirmed" ## Retrieves a list of events Retrieves a list of events. <strong>Note:</strong> This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to <a href='/api/usage/pagination-rest'>Make paginated requests to the REST Admin API</a>. ### Endpoint /admin/api/#{api_version}/events.json (GET) ### Parameters * api_version (required): * created_at_max: Show events created at or before this date and time. (format: 2014-04-25T16:15:47-04:00) * created_at_min: Show events created at or after this date and time. (format: 2014-04-25T16:15:47-04:00) * fields: Show only certain fields, specified by a comma-separated list of field names. * filter: Show events of certain resources, specified by a comma-separated list of resource names. * limit: The number of results to show. * since_id: Show only results after the specified ID. * verb: Show events of a certain type. ### Responses #### 200 Retrieves a list of events Examples: ##### Retrieve a list of all events for a shop Request: ``` GET /admin/api/unstable/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":164748010,"subject_id":450789469,"created_at":"2008-01-10T06:00:00-05:00","subject_type":"Order","verb":"confirmed","arguments":["#1001","Bob Norman"],"body":null,"message":"Received new order <a href=\"https://jsmith.myshopify.com/admin/orders/450789469\">#1001</a> by Bob Norman.","author":"Shopify","description":"Received new order #1001 by Bob Norman.","path":"/admin/orders/450789469"},{"id":365755215,"subject_id":632910392,"created_at":"2008-01-10T07:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Nano - 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/632910392\">IPod Nano - 8GB</a>.","author":"Shopify","description":"Product was created: IPod Nano - 8GB.","path":"/admin/products/632910392"},{"id":677313116,"subject_id":921728736,"created_at":"2008-01-10T08:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Touch 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/921728736\">IPod Touch 8GB</a>.","author":"Shopify","description":"Product was created: IPod Touch 8GB.","path":"/admin/products/921728736"}]} ``` ##### Retrieve a list of all events from a specific order Request: ``` GET /admin/api/unstable/orders/450789469/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":103105390,"subject_id":450789469,"created_at":"2008-01-10T05:00:00-05:00","subject_type":"Order","verb":"authorization_success","arguments":["389404469","210.94","USD"],"body":null,"message":"A transaction was authorized.","author":"Shopify","description":"A transaction was authorized.","path":"/admin/orders/450789469"},{"id":164748010,"subject_id":450789469,"created_at":"2008-01-10T06:00:00-05:00","subject_type":"Order","verb":"confirmed","arguments":["#1001","Bob Norman"],"body":null,"message":"Received new order <a href=\"https://jsmith.myshopify.com/admin/orders/450789469\">#1001</a> by Bob Norman.","author":"Shopify","description":"Received new order #1001 by Bob Norman.","path":"/admin/orders/450789469"},{"id":852065041,"subject_id":450789469,"created_at":"2008-01-10T09:00:00-05:00","subject_type":"Order","verb":"placed","arguments":[],"body":null,"message":"This order was created for Bob Norman from draft order <a href=\"https://jsmith.myshopify.com/admin/draft_orders/72885271\">#D1</a>.","author":"Shopify","description":"This order was created for Bob Norman from draft order #D1.","path":"/admin/orders/450789469"}]} ``` ##### Retrieve a list of all events related to products and orders Request: ``` GET /admin/api/unstable/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":164748010,"subject_id":450789469,"created_at":"2008-01-10T06:00:00-05:00","subject_type":"Order","verb":"confirmed","arguments":["#1001","Bob Norman"],"body":null,"message":"Received new order <a href=\"https://jsmith.myshopify.com/admin/orders/450789469\">#1001</a> by Bob Norman.","author":"Shopify","description":"Received new order #1001 by Bob Norman.","path":"/admin/orders/450789469"},{"id":365755215,"subject_id":632910392,"created_at":"2008-01-10T07:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Nano - 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/632910392\">IPod Nano - 8GB</a>.","author":"Shopify","description":"Product was created: IPod Nano - 8GB.","path":"/admin/products/632910392"},{"id":677313116,"subject_id":921728736,"created_at":"2008-01-10T08:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Touch 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/921728736\">IPod Touch 8GB</a>.","author":"Shopify","description":"Product was created: IPod Touch 8GB.","path":"/admin/products/921728736"}]} ``` ##### Retrieve a list of events related to products that were deleted Request: ``` GET /admin/api/unstable/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[]} ``` ##### Retrieve a list of events that occured at the specified time Request: ``` GET /admin/api/unstable/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":677313116,"subject_id":921728736,"created_at":"2008-01-10T08:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Touch 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/921728736\">IPod Touch 8GB</a>.","author":"Shopify","description":"Product was created: IPod Touch 8GB.","path":"/admin/products/921728736"}]} ``` ##### Retrieve all events after the specified ID Request: ``` GET /admin/api/unstable/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":365755215,"subject_id":632910392,"created_at":"2008-01-10T07:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Nano - 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/632910392\">IPod Nano - 8GB</a>.","author":"Shopify","description":"Product was created: IPod Nano - 8GB.","path":"/admin/products/632910392"},{"id":677313116,"subject_id":921728736,"created_at":"2008-01-10T08:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Touch 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/921728736\">IPod Touch 8GB</a>.","author":"Shopify","description":"Product was created: IPod Touch 8GB.","path":"/admin/products/921728736"}]} ``` ##### Retrieve all events from a specific product Request: ``` GET /admin/api/unstable/products/921728736/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":677313116,"subject_id":921728736,"created_at":"2008-01-10T08:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Touch 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/921728736\">IPod Touch 8GB</a>.","author":"Shopify","description":"Product was created: IPod Touch 8GB.","path":"/admin/products/921728736"}]} ``` ##### Retrieve an event after a specific ID using <code>since_id</code> Request: ``` GET /admin/api/unstable/orders/450789469/events.json ``` Response: ``` HTTP/1.1 200 OK {"events":[{"id":852065041,"subject_id":450789469,"created_at":"2008-01-10T09:00:00-05:00","subject_type":"Order","verb":"placed","arguments":[],"body":null,"message":"This order was created for Bob Norman from draft order <a href=\"https://jsmith.myshopify.com/admin/draft_orders/72885271\">#D1</a>.","author":"Shopify","description":"This order was created for Bob Norman from draft order #D1.","path":"/admin/orders/450789469"}]} ``` ## Retrieves a single event Retrieves a single event by its ID ### Endpoint /admin/api/#{api_version}/events/{event_id}.json (GET) ### Parameters * api_version (required): * event_id (required): * fields: Show only certain fields, specified by a comma-separated list of field names. ### Responses #### 200 Retrieves a single event Examples: ##### Retrieves a single event by its ID Request: ``` GET /admin/api/unstable/events/677313116.json ``` Response: ``` HTTP/1.1 200 OK {"event":{"id":677313116,"subject_id":921728736,"created_at":"2008-01-10T08:00:00-05:00","subject_type":"Product","verb":"create","arguments":["IPod Touch 8GB"],"body":null,"message":"Product was created: <a href=\"https://admin.myshopify.io/store/jsmith/admin/products/921728736\">IPod Touch 8GB</a>.","author":"Shopify","description":"Product was created: IPod Touch 8GB.","path":"/admin/products/921728736"}} ``` ## Retrieves a count of events Retrieves a count of events ### Endpoint /admin/api/#{api_version}/events/count.json (GET) ### Parameters * api_version (required): * created_at_max: Count only events created at or before this date and time. (format: 2014-04-25T16:15:47-04:00) * created_at_min: Count only events created at or after this date and time. (format: 2014-04-25T16:15:47-04:00) ### Responses #### 200 Retrieves a count of events Examples: ##### Count all events Request: ``` GET /admin/api/unstable/events/count.json ``` Response: ``` HTTP/1.1 200 OK {"count":3} ``` ##### Count of the number of events since a particular time Request: ``` GET /admin/api/unstable/events/count.json ``` Response: ``` HTTP/1.1 200 OK {"count":1} ```