Event Notifications

This section includes expanded definitions of the request and response bodies for the Custom Store /events endpoint.

Info If your cart or marketplace has data that you want to make available in ShipStation, but does not fit into one of these fields, contact us about making an integration using the full ShipStation ECommerceAPI.

The HTTP POST request to /events allows ShipStation to write shipment information back to your Custom Store when you ship orders.

Your web endpoint should return a response that indicates what the result of each notification was. The result of any event that your web endpoint does not recognize is still considered a success. This is so that ShipStation can continue adding new events without causing errors in stores that do not support them.

Example Request

ShipStation will contact the web endpoint when certain actions are taken so your system can be notified of those events. Each notification could contain a number of different events, but it is not necessary for your web endpoint to process every event type. We recommend that all Custom Store integrations listen for the fulfilled event so that you can update your cart or marketplace with tracking info from the shipped order.

POST /events HTTP/1.1
Host: api.my-store.com
Authorization: Basic ZGVtbzpwQDU1dzByZA==
Content-Type: application/json
Accept: application/json

{
  "events": [
    {
      "event_id": "evt_w6W9yp8sPJ9RGb9fY4T",
      "type": "fulfilled",
      "occurred_at": "2020-01-18T05:13:14.000Z",
      "shipment_id": "shp_X735ioRGb9fQqkldA9pz2",
      "tracking_number": "1Z918478194858101",
      "carrier_code": "fedex",
      "service_code": "fedex_ground",
      "orders": [
        {
          "order_id": "QsPJ9R-CfY4 BjnieMw68-Gb9TW9yp",
          "items": [
            {
              "item_id": "9TWjnieMw6-89ypRCfY4XBGb-QsPJ9",
              "quantity": 3
            }
          ]
        },
        {
          "order_id": "9374jksd-Dkso Dkw-snieMw68",
          "items": [
            {
              "item_id": "op29ypfY4-19923k-PJ9oi81m",
              "quantity": 1
            },
            {
              "item_id": "u7msh2ETxpUv-2751XFqqAzpem6",
              "quantity": 1
            }
          ]
        }
      ]
    }
  ]
}

Example Response

The Custom Store implementation can simply respond with an HTTP 200 or 204 response to indicate that the events were received successfully. No response body is necessary.

Some Custom Store implementations may wish to indicate a partial success. For example, some of the events were received successfully, but others were not and should be re-sent again later. In this case the API should respond with an HTTP status of 207, and the body should indicate the status of each event.

{
  "events": [
    {
      "event_id": "evt_w6W9yp8sPJ9RGb9fY4T",
      "status": "success"
    },
    {
      "event_id": "evt_isWE52SXwjkdd92sJeOqlY",
      "status": "failure"
    }
  ]
}

Request Property Definitions

Name Type Required? Description
events object[] Yes An array containing each notification to process.
events[].event_id string Yes An id to allow the response to differentiate between events.
events[].type string Yes The event type being sent. By default this will only be fulfilled, but your integration can request additional events.
events[].occurred_at string Yes Format: ISO 8601. Timestamp of when the event occurred.
events[].shipment_id string Yes The shipment id.
events[].tracking_number string No The tracking number associated with the shipping item.
events[].carrier_code string No The carrier code that is associated with the notification event.
events[].service_code string No The service code that is associated with the notification event.
events[].orders[] object[] Yes An array objects that contains info on the orders associated with this notification event.
events[].orders[].order_id string Yes An order id associated with the order items.
events[].orders[].items[] object[] Yes An array of objects which represent an item that's a part of the order.
events[].orders[].items[].item_id string Yes The ID used by your cart or marketplace to uniquely identify this line item on the order.
events[].orders[].items[].quantity string Yes The number of products being sold as part of this line item.

Response Property Definitions

Name Type Required? Description
events object[] Yes An array containing each notification to process.
events[].event_id string Yes An id to allow the response to differentiate between events.
events[].status string Yes Status of the order related to the event:
Value:
  • awaiting_payment
  • awaiting_shipment
  • cancelled
  • cancelled
  • completed
  • on_hold
  • pending_fulfillment