API Reference

VTEX Shipping Network
VTEX Shipping Network Labels Integration

This feature is in beta, which means that we are working to improve it. If you have any questions, please contact our Support.

VTEX Shipping Network is the solution that uses order tracking data directly from carriers to keep merchants and shoppers up to date with the status of each delivery.


The VTEX Shipping Network module is responsible for integrating your store with carriers via a defined protocol. The integration is divided into three workflows:

  1. Notification
  2. Tracking
  3. Shipping label creation

A Package created in the VTEX Shipping Network module (SPN) has the following lifecycle, including these workflows:

  1. The cycle begins when an order is invoiced in the OMS module, which results in SPN creating all of its packages. The new packages will have an Invoiced status.
  2. The Carrier App will then receive a notification request for all packages, and their status will move to carrier_notified.
  3. All packages can now have their associated Shipping Label created. Once each label is successfully created, its associated package status moves to label_issued.
  4. Tagged by its Shipping Label, the package can now be delivered, and while it is in transit, the SPN module requests the Carrier App for tracking updates until the package is tagged as Delivered.

The Package lifecycle ends when it is delivered.

{"base64":"  ","img":{"width":3334,"height":1508,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":166432,"url":""}}


The endpoint described in this document is responsible for creating the Shipping Labels of all the packages associated with an order. Given an orderId, it will provide a URL that when accessed downloads a pdf file containing the Shipping Labels.

The URL returned by the API is valid for 5 days from the moment it was requested, and expires after that period. If the file is required after the link has expired, only a new request with the same orderId will provide a new valid URL.

Be aware that VTEX Shipping Network only keeps track of Fulfillment orders, therefore, the orderId used on the endpoint must have their origin as Fulfillment. All Fulfillment Orders contain a prefix, for example:

  • Order with prefix: 00-1307463503290-01
  • Order without prefix: 1307463503290-01

The order origin can be found using the Orders API documentation. If the order has other origins rather than Fulfillment, the Order.sellerOrderId field should be used, as it references the Fulfillment Order.


Order with Fulfillment origin:

POST -{orderId}

Order with another origin:

POST -{sellerOrderId}

The authentication headers must be used to call this endpoint:

  • X-VTEX-API-AppKey
  • X-VTEX-API-AppToken

To use the endpoint, the appKey and appToken must have TransportationViewer or TransportationAdmin License Manager resources and roles associated with them.

Example cURL request

curl --location --request POST '{{orderId}}?an={{accountName}}' \
--header 'X-VTEX-API-AppToken: {{token}}' \
--header 'X-VTEX-API-AppKey: {{appKey}}'


The successful response has the following format:

  • Status code: 200 (OK)
  • Response body:

"url" : ""

This endpoint can return other status codes in the following scenarios:

400Package {packageId} has an invalid state!One or more packages associated with the orderId have an invalid status. This might happen if the carrier app has not been notified about the package yet. Retry the operation in a few minutes.
401UnauthorizedAuthentication credentials are missing. Make sure to include the headers X-VTEX-API-AppToken and X-VTEX-API-AppKey.
403reason: User does not have access to the resources [TransportationAdmin]Forbidden response status code indicates that the request has not been completed because it lacks valid authentication credentials for the requested resource. In this case, the header values X-VTEX-API-AppToken or X-VTEX-API-AppKey are invalid.
404Not FoundThe orderId provided does not belong to any existing order. This might happen if the orderId does not contain the correct prefix.
500Internal Server ErrorUnexpected error.

Configuring shipping labels printing format

In the VTEX Admin, you can configure the shipping labels printing format as a A4 (297x210mm) or a ZPL (Zebra Programming Language) extension. You will find the instructions in our Help Center article Pronto para envio.

Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page