Using the Nylas Order Consolidation API
The Order Consolidation API works alongside Nylas ExtractAI to allow you to retrieve order and tracking information for your end users' e-commerce purchases.
This page explains how to use the Order Consolidation API.
How the Order Consolidation API works
After you activate ExtractAI for your application, Nylas automatically starts inspecting end users' incoming email messages to determine if they contain information about e-commerce orders or shipments. If they do, you can query the Order Consolidation API to get the relevant email messages, as well as order and tracking information.
Before you begin
To follow along with the instructions on this page, you first need to complete the following prerequisites:
- Sign up for a Nylas developer account.
- Create a v3 Nylas application or Sandbox.
- Create a provider auth app for your development, staging, or production application (Google or Microsoft Azure) and connector with at least the following scopes:
- Google:
gmail.readonly - Microsoft:
Mail.Read,Mail.Read.Shared(Required if you're extracting data from an organization-specific email account, like a work or school account.)
- Google:
- Authenticate a grant.
- Set up ExtractAI for your Nylas application.
Get a list of orders for a grant
Now that you have ExtractAI configured for your Nylas application, you can make a GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-order request to get a list of orders for a specific grant.
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/consolidated-order' \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' {
"request_id": "1",
"next_cursor": "2",
"data": [
{
"id": "7d34d328-3869-4b23-b8c1-ddcf65a38ae0",
"application_id": "<NYLAS_APPLICATION_ID>",
"grant_id": "<NYLAS_GRANT_ID>",
"object": "order",
"created_at": 1716330978,
"updated_at": 1716332784,
"order_id": "9542212-368142",
"merchant_name": "Nylas Example",
"merchant_domain": "example.com",
"purchase_date": 1632726000,
"currency": "USD",
"order_total": 812,
"tax_total": 16,
"discount_total": null,
"shipping_total": null,
"gift_card_total": null,
"products": [{
"name": "Sensitive Skin Bar Soap - 4 oz.",
"image_url": null,
"quantity": 1,
"unit_price": 197
}],
"provider_message_ids": ["<MESSAGE_ID>"]
},
{
"id": "62e38e87-5c72-484e-8717-7037176b753a",
"application_id": "<NYLAS_APPLICATION_ID>",
"grant_id": "<NYLAS_GRANT_ID>",
"object": "order",
"created_at": 1716330974,
"updated_at": 1716332855,
"order_id": "51454083051",
"merchant_name": "Nylas Example",
"merchant_domain": "example.com",
"purchase_date": 1664866800,
"currency": "USD",
"order_total": 456,
"tax_total": 36,
"discount_total": null,
"shipping_total": null,
"gift_card_total": null,
"products": [{
"name": "Lip Balm & Scrub",
"image_url": null,
"quantity": 1,
"unit_price": 420
}],
"provider_message_ids": ["<MESSAGE_ID>"]
}
]
} 🔍 If the end user hasn't received any email messages that contain order information, the Order Consolidation API returns an empty response.
Get a list of shipments for a grant
You can also make a GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-shipment request to get a list of shipments for a specific grant.
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/consolidated-shipment' \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' {
"request_id": "1",
"next_cursor": "2",
"data": [
{
"object": "shipment",
"id": "27be79f8-2175-42bd-9a3b-61968d850b2e",
"created_at": 1716330979,
"updated_at": 1716330979,
"application_id": "<NYLAS_APPLICATION_ID>",
"grant_id": "<NYLAS_GRANT_ID>",
"tracking_provider_message_ids": ["<MESSAGE_ID>"],
"carrier_name": "Nyla Global Express Inc.",
"tracking_number": "<CARRIER_TRACKING_NUMBER>",
"tracking_link": "<CARRIER_TRACKING_LINK>",
"carrier_enrichment": {
"delivery_date": 1190906222,
"delivery_estimate": 0,
"delivery_status": {
"description": "delivered",
"carrier_description": "Delivered"
},
"ship_to_address": {
"city": "SAN FRANCISCO",
"postal_code": "94102",
"state_province_code": "CA",
"country_code": "US",
"country_name": "United States"
},
"package_activity": [
{
"status": {
"description": "delivered",
"carrier_description": "Delivered"
},
"location": {
"city": "SAN FRANCISCO",
"postal_code": "94102",
"state_province_code": "CA",
"country_code": "US",
"country_name": "United States"
},
"carrier_location": "",
"timestamp": 1190906222
},
{
"status": {
"description": "out_for_delivery",
"carrier_description": "On vehicle for delivery"
},
"location": {
"city": "SAN FRANCISCO",
"postal_code": "94102",
"state_province_code": "CA",
"country_code": "US",
"country_name": "United States"
},
"carrier_location": "",
"timestamp": 1190888940
},
{
"status": {
"description": "in_transit",
"carrier_description": "Arrived at sorting location"
},
"location": {
"city": "HOLMEN",
"postal_code": "54636",
"state_province_code": "WI",
"country_code": "US",
"country_name": "United States"
},
"carrier_location": "",
"timestamp": 1190677980
},
{
"status": {
"description": "info_received",
"carrier_description": "Shipment information sent to carrier"
},
"location": {
"city": "",
"postal_code": "54612",
"state_province_code": "",
"country_code": "US",
"country_name": "United States"
},
"carrier_location": "",
"timestamp": 1190657340
}
],
"signature_required": false
},
"order": {
"order_id": "9542212-368142",
"purchase_date": 1632726000,
"currency": "USD",
"merchant_name": "Nylas Example",
"merchant_domain": "example.com",
"order_total": 812,
"tax_total": 16,
"discount_total": null,
"shipping_total": null,
"gift_card_total": null,
"products": [{
"name": "Sensitive Skin Bar Soap - 4 oz.",
"image_url": null,
"quantity": 1,
"unit_price": 197
}],
"order_provider_message_ids": ["<MESSAGE_ID>"]
}
}
]
} 🔍 If the end user hasn't received any email messages that contain tracking information, the Order Consolidation API returns an empty response.