Learn how to create webhooks and get order status and information from VTEX Pick and Pack API
VTEX Pick and Pack is a solution to streamline stores’ fulfillment processes by optimizing orders’ picking and packing, and the last-mile delivery. The solution is composed of the VTEX Fulfillment and the Last Mile modules.
This documentation explains how to make a request to the Get order status and information REST API to retrieve the status and details of an order in the VTEX Pick and Pack context. If you use this API to retrieve orders from other contexts, you will receive 404 error messages.
The order statuses in VTEX Pick and Pack do not correspond to the order flow and status of the Order Management System (OMS).
Before you start
Before making the request, you will need the following:
Basic authentication
Basic Authentication is a method for an HTTP user agent to provide a username and password when making a request. The system doesn't store API keys, they need to be generated every time there's a new request.
Below, you will find an Api-Key for the Development environment that you can use. To find the Api-Key of the environment in Production, Admin users can generate an API Key in the users section of their Pick and Pack settings.
Production (Prod)
_10{{alphanumericSequence}}
JSON Web Token (JWT)
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information as a JSON object between parties.
In order to authorize the API request, you will have to generate a JWT. For that, you will use the Api-Key from the previous section.
The first step is to create a token of authentication with the endpoint below. No authentication is required:
Endpoint
| Method | URL |
|---|---|
| POST | https://auth.pickingnpacking.com/prod/token |
Request body example
_10{_10 "apiKey": _10"db5a3cecfef9cb0a9815af7c2eb8f7d6:c400460c165cc9beb146ad4d757e3bb1a24ff15228c424a0bd7c37f0ac356c0f6230568705d93dd6ff68190c0eafe5a74cbb14229748f20d3e53cbcc790ba372"_10}
Response body example
_10{_10 "message": "success",_10 "data": _10"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ2.eyJob4N0bmFtZSI6Im5ld2J1c2luZXNzMDEiLCJpYXQiOjE2MzM3MjE1NzksImV4cCI6MTYzMzcyMjQ3OX0.7QRZpElg1HYgyJpE6QTNgE2IN3vXbzIfulBS0Bvyzds"_10}
Status codes
| Status code | Description |
|---|---|
| 200 | OK |
| 401 | Requires authentication |
| 400 | Bad request |
| 404 | Resource not found |
| 500 | Internal error |
Headers
After you have created the token of authentication, make the request to the endpoint once again, this time sending in the headers the following object:
_10// Headers_10{_10 "Authorization": "{{JWT}}"_10}
Get order status and information API
In order to get the VTEX Pick and Pack status and details of a given order, use the endpoint below:
Endpoint
| Method | URL |
|---|---|
| GET | https://legacy.pickingnpacking.com/prod/picking-tracking/{orderId} |
The
orderIdis the order's unique code and is the same used in OMS and all VTEX modules.
Authorization
Use the authorization retrieved from the steps listed in Before you start and insert it in the call's header.
Response body example
_41{_41 "message": "string",_41 "data": {_41 "hostname": "string",_41 "orderId": "string",_41 "fulfillmentStatus": "string",_41 "pickedItems": [_41 {_41 "image": "string",_41 "sellingPrice": "float",_41 "ean": "string",_41 "quantity": "number",_41 "name": "string",_41 "id": "string",_41 "refId": "string",_41 "categories": [_41 {_41 "name": "string",_41 "id": "string"_41 }_41 ]_41 }_41 ]_41 "shipping"?: {_41 "trackingId": "string",_41 "trackingStatus": "string",_41 "services"?: [_41 {_41 "serviceId": "string",_41 "agent"?: "string",_41 "vehicle"?: "string",_41 "courier": "string",_41 "trackingUrl"?: "string",_41 "serviceStatus": "string",_41 "evidences"?: "string",_41 "createdAt": "string"_41 }_41 ]_41 }_41 }_41}
Status codes
| Status code | Internal response Code | Message |
|---|---|---|
| 200 | OK | OK |
| 401 | 1000 | Internal server |
| 404 | 1001 | Resource not found |
| 400 | 1002 | OrderId is not found | Order not found by {orderId} |
| 500 | 1003 | Internal error |
Webhook
You will need to create a webhook to receive the response of the request, used for receiving notifications for invoicing purposes, for example.
Your webhook may have your desired setting for URL, path, method, and authentication, it is flexible.
The order’s information and status change notifications received will be an object like the following example:
Example
_10{_10 "orderId": "XDE-1253881550433-01",_10 "oldStatus": "PENDING",_10 "newStatus": "READY_FOR_PICKING",_10 "hostname": "picknpackstore"_10}
Order status in Pick and Pack
In the table below, you will find the possible order statuses in the VTEX Pick and Pack context:
| Status | Description |
|---|---|
| READY_FOR_HANDLING | An order imported from the Order Management System (OMS) that is ready to be fulfilled. |
| IDLE (Inactive) | The order was an external fulfillment, and VTEX Pick and Pack will not be able to process it. If the order is invoiced in OMS in a status different from Ready for invoicing, the system will also consider it an external fulfillment and change the order status to Idle. |
| READY_FOR_PICKING | The order was assigned to a picker and is depending on the picker’s confirmation to move to the next status. |
| PICKING | The picker is collecting the order items. |
| READY_FOR_PACKING | The picker has finished the picking process and the order is ready to be packed. |
| PACKING | The order’s items are being packed. |
| READY_FOR_INVOICING | The order can be invoiced. VTEX Pick and Pack solution does not invoice orders. |
| INVOICING | The invoice is being processed. |
| INVOICED | The order was invoiced. |
| PREPARING_SHIPPING | Shipping services are being created for the order. |
| READY_FOR_SHIPPING | Once Shipping Services are created, service is awaiting carrier pickup. |
| WAITING_FOR_DELIVERY_COMPANY | The order is packed and the shipping service was successfully created. |
| ON_ROUTE | The courier (driver) has collected the package in the physical store or warehouse, for example. |
| DELIVERED | The order was delivered to the customer. |
| RETURNED | The customer couldn’t be reached or refused to receive the package, so the order was returned. |
| WAITING_FOR_PICKUP | The package is ready to be picked up by the customer at the physical store or at another pickup point. |
| CANCELED | The order was canceled. |
The statuses above are related to VTEX Pick and Pack only, and do not correspond to the order flow and status of the Order Management System (OMS).