Event

Events are generated by specific haravan 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.

#

Events are generated by these haravan resources:

Article events

VerbMessageDescription
createNew article created: article_urlThe article was created.
destroyarticle_url was destroyed.The article was deleted.
publishedarticle_url was published.The article was published.
unpublishedarticle_url was unpublished.Article was unpublished.
updatearticle_url was updated (but its published state was not changed).Article was updated.

Blog events

VerbMessageDescription
createNew blog created: new_blog_urlThe blog was created.
destroyblog_name was destroyed.The blog was deleted.
updateblog_name was updated.Blog was updated.

Collection events

VerbMessageDescription
createNew collection created: collection_urlThe collection was created.
destroycollection_url was destroyed.The collection was deleted.
publishedcollection_url was published.The collection was published.
unpublishedcollection_url was hidden.Collection was hidden.
updatecollection_url was updated.Collection was updated.

Comment events

VerbMessageDescription
createNew comment for article_url: comment_excerptThe 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
VerbMessageDescription
authorization_failureThe customer, unsuccessfuly, tried to authorize: money_amountAuthorization failed. The funds cannot be captured.
authorization_pendingAuthorization for money_amount is pending.Authorization failed. The funds cannot be captured.
authorization_successThe customer successfuly authorized us to capture: money_amountAuthorization was successful and the funds are available for capture.
cancelledOrder was cancelled by shop_staff_name.The order was cancelled.
capture_failureWe failed to capture: money_amountCapture failed. The funds cannot be transferred to the shop.
capture_pendingCapture for money_amount is pending.Capture is in process. The funds are not yet available to the shop.
capture_successWe succesfully captured: money_amountCapture was succesfull and the funds are now available to the shop.
closedOrder was closed.The order was closed.
confirmedRecieved a new order: order_number by customer_name.The order was confirmed.
fulfillment_cancelledWe 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_pendingWe 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_successWe successfuly fulfilled line_items.Fulfillment was succesfull for one or more line_items.
mail_sentmessage_type email was sent to the customer.An email was sent to the customer.
placedOrder was placed.An order was placed by the customer.
re_openedOrder was re-opened.The order was re-opened.
refund_failureWe failed to refund money_amount.Refund failed. The funds are still with the shop.
refund_pendingRefund of money_amount is still pending.Refund is in process. The funds are still with shop.
refund_successWe successfuly refunded money_amount.Refund was successful. The funds have been transferred to the customer.
restock_line_itemsWe restocked number_of_line_items.One or more of the order's line items have been restocked.
sale_failureThe customer failed to pay money_amount.Sale failed. The funds are not available to the shop.
sale_pendingThe money_amount is pending.Sale is in process. The funds are not yet available to the shop.
sale_successWe successfully captured money_amount.We successfuly captured money_amount. Sale was successful. The funds are now with the shop.
updateorder_number was updated.The order was updated.
void_failureWe failed to void the authorization.Voiding the authorization failed. The authorization is still valid.
void_pendingAuthorization void is pending.Voiding the authorization is in process. The authorization is still valid.
void_successWe successfully voided the authorization.Voiding the authorization was successful. The authorization is no longer valid.

Page events

VerbMessageDescription
createNew page created: page_urlThe page was created.
destroypage_url was destroyed.The page was deleted.
publishedpage_url was published.The page was published.
unpublishedpage_url was hidden.Page was hidden.
updatepage_url was updated.Page was updated.

Product events

VerbMessageDescription
createNew product created: product_titleThe product was created.
destroyproduct_name was destroyed.The product was deleted.
publishedproduct_title was published.The product was published.
unpublishedproduct_title was hidden.Product was hidden.
updateproduct_title was updated.Product was updated.

What can you do with Event?

The haravan 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" : "2008-01-10T11:00:00-05: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
{ "description" : "Received a new order" }

A plain text description of the event

path
{ "path" : "/admin/orders/1234" }
{ "path" : "null" }

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.

subject_id
{ "subject_id" : "450789469" }

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


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/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: 2008-12-31 03:00)

created_at_max

Show events created at or before date and time (format: 2008-12-31 03: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

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 haravan blog.

GET /admin/events.json
View Response
HTTP/1.1 200 OK
{
  "events": [
    {
      "arguments": [
        "IPod Touch 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 677313116,
      "subject_id": 921728736,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/921728736"
    },
    {
      "arguments": [
        "IPod Nano - 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 365755215,
      "subject_id": 632910392,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/632910392\">IPod Nano - 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/632910392"
    },
    {
      "arguments": [
        "#1001",
        "Bob Norman"
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 164748010,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "confirmed",
      "message": "Received new order <a href=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "haravan",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469\/transactions\/#1001"
    }
  ]
}

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

GET /admin/events.json?created_at_min=2007-12-31 21:00:00
View Response
HTTP/1.1 200 OK
{
  "events": [
    {
      "arguments": [
        "#1001",
        "Bob Norman"
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 164748010,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "confirmed",
      "message": "Received new order <a href=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "haravan",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469\/transactions\/#1001"
    }
  ]
}

Get all the events from a particular order

GET /admin/orders/#{id}/events.json
View Response
HTTP/1.1 200 OK
{
  "events": [
    {
      "arguments": [
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 852065041,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "placed",
      "message": "Order was placed",
      "author": "haravan",
      "description": "Order was placed",
      "path": "\/admin\/orders\/450789469\/transactions\/"
    },
    {
      "arguments": [
        "#1001",
        "Bob Norman"
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 164748010,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "confirmed",
      "message": "Received new order <a href=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "haravan",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469\/transactions\/#1001"
    },
    {
      "arguments": [
        "389404469",
        "210.94",
        "USD"
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 103105390,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "authorization_success",
      "message": "The customer successfully authorized $409.94 USD on Visa •••• •••• •••• 4242",
      "author": "haravan",
      "description": "The customer successfully authorized $409.94 USD on Visa •••• •••• •••• 4242",
      "path": "\/admin\/orders\/450789469\/transactions\/389404469"
    }
  ]
}

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": [
    {
      "arguments": [
        "#1001",
        "Bob Norman"
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 164748010,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "confirmed",
      "message": "Received new order <a href=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "haravan",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469\/transactions\/#1001"
    }
  ]
}

Get all the events from a particular product

GET /admin/products/#{id}/events.json
View Response
HTTP/1.1 200 OK
{
  "events": [
    {
      "arguments": [
        "IPod Touch 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 677313116,
      "subject_id": 921728736,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/921728736"
    }
  ]
}

Get all the events after the specified ID

GET /admin/events.json?since_id=164748010
View Response
HTTP/1.1 200 OK
{
  "events": [
    {
      "arguments": [
        "IPod Nano - 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 365755215,
      "subject_id": 632910392,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/632910392\">IPod Nano - 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/632910392"
    },
    {
      "arguments": [
        "IPod Touch 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 677313116,
      "subject_id": 921728736,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/921728736"
    }
  ]
}

Only get events related to Products or Orders

GET /admin/events.json?filter=Product,Order
View Response
HTTP/1.1 200 OK
{
  "events": [
    {
      "arguments": [
        "IPod Touch 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 677313116,
      "subject_id": 921728736,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/921728736"
    },
    {
      "arguments": [
        "IPod Nano - 8GB"
      ],
      "body": null,
      "created_at": "2007-12-31T19:00:00-05:00",
      "id": 365755215,
      "subject_id": 632910392,
      "subject_type": "Product",
      "verb": "create",
      "message": "created a new product: <a href=\"\/admin\/products\/632910392\">IPod Nano - 8GB<\/a>.",
      "author": "haravan",
      "description": null,
      "path": "\/admin\/products\/632910392"
    },
    {
      "arguments": [
        "#1001",
        "Bob Norman"
      ],
      "body": null,
      "created_at": "2008-01-10T11:00:00-05:00",
      "id": 164748010,
      "subject_id": 450789469,
      "subject_type": "Order",
      "verb": "confirmed",
      "message": "Received new order <a href=\"\/admin\/orders\/450789469\">#1001<\/a> by Bob Norman",
      "author": "haravan",
      "description": "Received new order #1001 by Bob Norman",
      "path": "\/admin\/orders\/450789469\/transactions\/#1001"
    }
  ]
}

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/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": {
    "arguments": [
      "IPod Touch 8GB"
    ],
    "body": null,
    "created_at": "2007-12-31T19:00:00-05:00",
    "id": 677313116,
    "subject_id": 921728736,
    "subject_type": "Product",
    "verb": "create",
    "message": "created a new product: <a href=\"\/admin\/products\/921728736\">IPod Touch 8GB<\/a>.",
    "author": "haravan",
    "description": null,
    "path": "\/admin\/products\/921728736"
  }
}
GET/admin/events/count.json
created_at_min

Count events created at or after date and time (format: 2008-12-31 03:00)

created_at_max

Count events created at or before date and time (format: 2008-12-31 03:00)

Count all the events

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

Count the number of events since a particular time

GET /admin/events/count.json?created_at_min=2007-12-31 21:00:00
View Response
HTTP/1.1 200 OK
{
  "count": 1
}