Order Level Events

Before an order hits the road, many things happen behind the scenes. To keep End Customers informed every step of the way, Ingrid Delivery Tracking offers Order Level Events.

PublishOrderEvent

The PublishOrderEvent endpoint allows you to change the state of the order in the Ingrid system. It is designed to be used by the Merchant's backend system.

POST v1/events_gateway/events.publishOrderEvent HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer <BASE64-ENCODED-API-TOKEN>

{
    "site_id": "f8212472-9c57-4af4-b4fb-f39da348122a",
    "external_id": "433322324",
    "occurred_at": "2019-01-01T12:00:00Z",
    "prepared": {
        "promises": {
            "estimated_submission_time": {
                "earliest": "2019-01-01T12:00:00Z",
                "latest": "2019-01-01T12:00:00Z"
            },
            "estimated_delivery_time": {
                "earliest": "2019-01-01T12:00:00Z",
                "latest": "2019-01-01T12:00:00Z"
            }
        }
    }
}

PublishOrderEvent is used to change the state of the order in the Ingrid system. It comprises the following required fields:

• site_id - the id of the site in the Ingrid system
• external_id - the id of the order in the merchant's system
• occurred_at - the time the event happened
• awaiting_supplier | prepared | linehaul | submitted - a JSON object representing possible event variants and containing event-related information

And an optional field:

• transport_id - the transport id is used to group events with the same transport. If not provided, default transport will be used.

Event types and payloads

Awaiting supplier

This event is used to indicate that the order is awaiting the supplier. You can specify the promises for the rest of the delivery.

{
  // ...
  "awaiting_supplier": {
    "promises": {
      "estimated_submission_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      },
      "estimated_delivery_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      }
    }
  }
}

awaiting_supplier is an object with the following fields:

• promises - the promises for the rest of the delivery process
• promises.estimated_submission_time - the Promise time when the order will be submitted to the carrier
• promises.estimated_delivery_time - the Promise time when the order will be delivered to the customer

Prepared

This event is used to indicate that the order is prepared for shipping. You can specify the promises for the rest of the delivery process.

{
  // ...
  "prepared": {
    "promises": {
      "estimated_submission_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      },
      "estimated_delivery_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      }
    }
  }
}

prepared is an object with the following fields:

• promises - the promises for the rest of the delivery process
• promises.estimated_submission_time - the Promise time when the order will be submitted to the carrier
• promises.estimated_delivery_time - the Promise time when the order will be delivered to the customer

Line haul

This event is used to indicate that the order is in line haul process. Line haul is a process of transporting goods from the warehouse to the carrier's hub. This event only makes sense for orders that are shipped with the line haul. You can specify the promises for the rest of the delivery process.

{
  // ...
  "linehaul": {
    "promises": {
      "estimated_submission_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      },
      "estimated_delivery_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      }
    }
  }
}

linehaul is an object with the following fields:

• promises - the promises for the rest of the delivery process
• promises.estimated_submission_time - the Promise time when the order will be submitted to the carrier
• promises.estimated_delivery_time - the Promise time when the order will be delivered to the customer

Submitted

This event is used to indicate that the order is submitted to the carrier. You can specify the promises for the rest of the delivery process.

{
  // ...
  "submitted": {
    "promises": {
      "estimated_delivery_time": {
        "earliest": "2021-01-01T00:00:00Z",
        "latest": "2021-01-01T00:00:00Z"
      }
    }
  }
}

submitted is an object with the following fields:

• promises - the promises for the rest of the delivery process
• promises.estimated_delivery_time - the Promise time when the order will be delivered to the customer

Promises

Promises are used to control promises that are shown to the customer.

{
    "earliest": "2021-01-01T00:00:00Z",
    "latest": "2021-01-01T00:00:00Z"
},

Each promise has two fields:

• earliest - the earliest time when the event can happen (required) - RFC3339 format
• latest - the latest time when the event can happen (required) - RFC3339 format

Full day promise

To indicate that the part of the delivery can happen at any time during the day, you can use the following format (the same date for earliest and latest):

{
  "earliest": "2021-01-24T00:00:00Z",
  "latest": "2021-01-24T00:00:00Z"
}

Time of day range

To indicate that the part of the delivery can happen from, for example, 6:00 to 18:00, you can use the following format:

{
  "earliest": "2021-01-24T06:00:00Z",
  "latest": "2021-01-24T18:00:00Z"
}