The Order Consolidation API works alongside Nylas ExtractAI to let you retrieve order, shipment, and return information for your users’ e-commerce purchases.
This page explains how to use the Order Consolidation API.
How the Order Consolidation API works
After you activate ExtractAI, Nylas automatically starts inspecting users’ incoming messages to determine if they contain information about e-commerce orders, shipments, or returns. If they do, you can query the Order Consolidation API to get the relevant messages.
Get a list of orders for a grant
Make a GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-order request to get a list of orders for a specific grant.
curl --location '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 user hasn’t received any messages that contain order information, the Order Consolidation API returns an empty response.
Get a list of shipments for a grant
Make a GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-shipment request to get a list of shipments for a specific grant.
curl --location '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 user hasn’t received any messages that contain tracking information, the Order Consolidation API returns an empty response.
Get a list of returns for a grant
Make a GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-return request to get a list of returns for a specific grant. If Nylas can link a return to its original order (for example, if the message containing the return information includes the original order number) it returns that information in the order_provider_message_ids field.
curl --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/consolidated-return' \ --header 'Accept: application/json, application/gzip' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --header 'Content-Type: application/json'{ "request_id": "1", "next_cursor": null, "data": [ { "id": "edd7b24b-a2c9-4bf9-8237-6b4732859873", "application_id": "<NYLAS_APPLICATION_ID>", "grant_id": "<NYLAS_GRANT_ID>", "object": "return", "created_at": 1734119328, "updated_at": 1734119328, "return_provider_message_ids": ["<MESSAGE_ID>"], "returns_date": 1732041900, "refund_total": 0, "order": { "order_id": "4601878991", "purchase_date": 0, "currency": null, "merchant_name": "Nylas Example", "merchant_domain": "example.com", "order_total": null, "tax_total": null, "discount_total": null, "shipping_total": null, "gift_card_total": null, "products": [], "order_provider_message_ids": null } }, { "id": "1c4457d2-4be7-464c-9bf3-393e43ccc29e", "application_id": "<NYLAS_APPLICATION_ID>", "grant_id": "<NYLAS_GRANT_ID>", "object": "return", "created_at": 1734119328, "updated_at": 1734119328, "return_provider_message_ids": ["<MESSAGE_ID>"], "returns_date": 1732041998, "refund_total": 0, "order": { "order_id": "4601878991", "purchase_date": 1732041901, "currency": "USD", "merchant_name": "Nylas Example", "merchant_domain": "example.com", "order_total": 5863, "tax_total": null, "discount_total": null, "shipping_total": null, "gift_card_total": null, "products": [], "order_provider_message_ids": ["<MESSAGE_ID>"] } } ]}If the user hasn’t received any messages that contain return information, the Order Consolidation API returns an empty response.