Event

Events are generated by specific Shopify resources when specific things happen, such as the creation of an article, the placement or fulfillment of an order, the addition or deletion of a product, and so on. By requesting events, your app can get a "log" of important occurrences in the operation of a shop.

Caution

The events returned by the Events API should not be considered to be realtime. Events might not appear in the list returned by the API until a few seconds after they've occurred. In rare cases (<1% of the time) it can take up to a few minutes for some events to appear.

Event

Events are generated by these Shopify resources:

Article events

Verb Message Description
create New article created: article_url The article was created.
destroy article_url was destroyed. The article was deleted.
published article_url was published. The article was published.
unpublished article_url was unpublished. Article was unpublished.
update article_url was updated (but its published state was not changed). Article was updated.

Blog events

Verb Message Description
create New blog created: new_blog_url The blog was created.
destroy blog_name was destroyed. The blog was deleted.
update blog_name was updated. Blog was updated.

Collection events

Verb Message Description
create New collection created: collection_url The collection was created.
destroy collection_url was destroyed. The collection was deleted.
published collection_url was published. The collection was published.
unpublished collection_url was hidden. Collection was hidden.
update collection_url was updated. Collection was updated.

Comment events

Verb Message Description
create New comment for article_url: comment_excerpt The comment was created.

Order events

There are a lot of events associated with orders. A few are generated by the order itself, but many more are generated by all the things that can happen in the time between the placing of an order and its closing or cancellation. Order events can be divided into the following categories:

  • Authorization: success, failure and pending
  • Capture: success, failure and pending
  • Email: for confirmation of the order, shipping and cancellation
  • Fulfillment: success, failure, pending, cancellation, restocking and update
  • Order: placing, confirmation, closing, reopening and cancellation
  • Refund: success, failure and pending
  • Sale: success, failure and pending
  • Void: success, failure and pending
Verb Message Description
authorization_failure The customer, unsuccessfully, tried to authorize: money_amount Authorization failed. The funds cannot be captured.
authorization_pending Authorization for money_amount is pending. Authorization failed. The funds cannot be captured.
authorization_success The customer successfully authorized us to capture: money_amount Authorization was successful and the funds are available for capture.
cancelled Order was cancelled by shop_staff_name. The order was cancelled.
capture_failure We failed to capture: money_amount Capture failed. The funds cannot be transferred to the shop.
capture_pending Capture for money_amount is pending. Capture is in process. The funds are not yet available to the shop.
capture_success We successfully captured: money_amount Capture was successful and the funds are now available to the shop.
closed Order was closed. The order was closed.
confirmed Received a new order: order_number by customer_name. The order was confirmed.
fulfillment_cancelled We cancelled number_of_line_items from being fulfilled by the third party fulfillment service. Fulfillment for one or more of the line_items failed.
fulfillment_pending We submitted number_of_line_items to the third party service. One or more of the line_items has been assigned to a third party service for fulfillment.
fulfillment_success We successfully fulfilled line_items. Fulfillment was successful for one or more line_items.
mail_sent message_type email was sent to the customer. An email was sent to the customer.
placed Order was placed. An order was placed by the customer.
re_opened Order was re-opened. The order was re-opened.
refund_failure We failed to refund money_amount. Refund failed. The funds are still with the shop.
refund_pending Refund of money_amount is still pending. Refund is in process. The funds are still with shop.
refund_success We successfully refunded money_amount. Refund was successful. The funds have been transferred to the customer.
restock_line_items We restocked number_of_line_items. One or more of the order's line items have been restocked.
sale_failure The customer failed to pay money_amount. Sale failed. The funds are not available to the shop.
sale_pending The money_amount is pending. Sale is in process. The funds are not yet available to the shop.
sale_success We successfully captured money_amount. We successfully captured money_amount. Sale was successful. The funds are now with the shop.
update order_number was updated. The order was updated.
void_failure We failed to void the authorization. Voiding the authorization failed. The authorization is still valid.
void_pending Authorization void is pending. Voiding the authorization is in process. The authorization is still valid.
void_success We successfully voided the authorization. Voiding the authorization was successful. The authorization is no longer valid.

Page events

Verb Message Description
create New page created: page_url The page was created.
destroy page_url was destroyed. The page was deleted.
published page_url was published. The page was published.
unpublished page_url was hidden. Page was hidden.
update page_url was updated. Page was updated.

Product events

Verb Message Description
create New product created: product_title The product was created.
destroy product_name was destroyed. The product was deleted.
published product_title was published. The product was published.
unpublished product_title was hidden. Product was hidden.
update product_title was updated. Product was updated.

What can you do with Event?

The Shopify API lets you do the following with the Event resource. More detailed versions of these general actions may be available:

Event Properties

arguments
{ "arguments" : "IPod Nano - 8GB" }

Refers to a certain event and its resources.

body
{ "body" : null }

A text field containing information about the event.

created_at
{ "created_at" : "2015-04-20T08:33:57-11:00" }

The date and time when the event was created. The API returns this value in ISO 8601 format.

id
{ "id" : 164748010 }

The unique numeric identifier for the event.

Description is deprecated and will be removed on 2017-03-01
description
{ "description" : "Received a new order" }

Human readable text that describes the event.

path
{ "path" : "/admin/orders/406514653/transactions/#1145" }

A relative URL to the resource the event is for (may be null)

message
{ "message" : "Received new order" }

Human readable text that describes the event (may contain limited HTML formatting).

subject_id
{ "subject_id" : 406514653 }

The id of the resource that generated the event.

subject_type
{ "subject_type" : "Order" }

The type of the resource that generated the event. This will be one of the following:

  • Article
  • Blog
  • Collection
  • Comment
  • Order
  • Page
  • Product
  • ApiPermission

verb
{ "verb" : "confirmed" }

The type of event that took place. Different resources generate different types of event; see Resources and their event verbs and messages (below) for details.

Endpoints

GET/admin/orders/450789469/events.json
limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)
since_id

Restrict results to after the specified ID

created_at_min

Show events created at or after date and time (format: 2014-04-25T16:15:47-04:00)

created_at_max

Show events created at or before date and time (format: 2014-04-25T16:15:47-04:00)

filter

Only show events specified in filter

verb

Only show events of a certain kind

fields

comma-separated list of fields to include in the response

Get a 'page' of events from a particular order

GET /admin/orders/#{id}/events.json?limit=1&page=2
View 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=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "Shopify",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469"
    }
  ]
}

The events you get back with this method are the same ones that show up in the shop's admin dashboard. Only events from the shop itself are returned; this does not include announcements from the Shopify blog.

GET /admin/events.json
View 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": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Touch 8GB.",
      "path": "\/admin\/products\/921728736"
    },
    {
      "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": "created a new product: <a href=\"\/admin\/products\/632910392\">IPod Nano - 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Nano - 8GB.",
      "path": "\/admin\/products\/632910392"
    },
    {
      "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=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "Shopify",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469"
    }
  ]
}

Only get events related to Products or Orders

GET /admin/events.json?filter=Product,Order
View 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": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Touch 8GB.",
      "path": "\/admin\/products\/921728736"
    },
    {
      "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": "created a new product: <a href=\"\/admin\/products\/632910392\">IPod Nano - 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Nano - 8GB.",
      "path": "\/admin\/products\/632910392"
    },
    {
      "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=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "Shopify",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469"
    }
  ]
}

Get all the events after the specified ID

GET /admin/events.json?since_id=164748010
View 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": "created a new product: <a href=\"\/admin\/products\/632910392\">IPod Nano - 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: 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": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Touch 8GB.",
      "path": "\/admin\/products\/921728736"
    }
  ]
}

The created_at_min and created_at_max parameters are interpreted using the shop's timezone.

GET /admin/events.json?created_at_min=2008-01-10 08:00:00
View 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": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Touch 8GB.",
      "path": "\/admin\/products\/921728736"
    }
  ]
}

Only get events related to Products that were deleted

GET /admin/events.json?filter=Product&verb=destroy
View Response
HTTP/1.1 200 OK
{
  "events": [
  ]
}

Get all the events from a particular product

GET /admin/products/#{id}/events.json
View 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": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "Shopify",
      "description": "created a new product: IPod Touch 8GB.",
      "path": "\/admin\/products\/921728736"
    }
  ]
}

Get all the events from a particular order

GET /admin/orders/#{id}/events.json
View 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": "Order was placed",
      "author": "Shopify",
      "description": "Order was placed",
      "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=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "Shopify",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469"
    },
    {
      "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"
    }
  ]
}
GET/admin/events/677313116.json
fields

comma-separated list of fields to include in the response

Shows the same fields as the list action.

GET /admin/events/#{id}.json
View 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": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
    "author": "Shopify",
    "description": "created a new product: IPod Touch 8GB.",
    "path": "\/admin\/products\/921728736"
  }
}
GET/admin/events/count.json
created_at_min

Count events created at or after date and time (format: 2014-04-25T16:15:47-04:00)

created_at_max

Count events created at or before date and time (format: 2014-04-25T16:15:47-04:00)

Count the number of events since a particular time

GET /admin/events/count.json?created_at_min=2008-01-10 08:00:00
View Response
HTTP/1.1 200 OK
{
  "count": 1
}

Count all the events

GET /admin/events/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 3
}