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

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

Ready for pickup

This event is used to indicate that order is ready for pickup in the pickup location.

{
  // ...
  "ready_for_pickup": {
    "pickup_deadline": "2021-01-01T00:00:00Z"
  }
}

ready_for_pickup is an object with the following fields:

pickup_deadline - the cutoff time when package collection - RFC3339 format.

Picked up by customer

This event is used to indicate that the customer collected the package.

{
  // ...
  "picked_up_by_customer": {}
}

picked_up_by_customer is an empty object.

Not collected by customer

This event is used to indicate that the package was not collected by the customer.

{
  // ...
  "not_collected_by_customer": {}
}

not_collected_by_customer is an empty object.

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

Ingrid Tracking Whole 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

Ingrid Tracking Range Promise

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"
}

Last updated: Fri, Dec 20, 06:15 AM