Frequently Asked Questions: How to invoice an order and send tracking updates? | How to integrate invoicing and tracking with marketplaces?

VTEX in your native language 🌎 Portuguese
,
1

This topic aims to foster knowledge in our community, mainly regarding the orders module and more specifically about how Invoicing and Tracking works for orders on the VTEX platform via API and its integration with marketplaces.

There are two distinct ways to carry out this process:

The first way is divided into just 2 steps:

  1. The invoicing and tracking information is sent to our platform through the Order invoice notification API. When invoicing is done referencing the order items, that information must also be sent at this point.
  2. Tracking updates are continuously sent to our platform through the Update order tracking status API until the package has been delivered to the recipient and this is reported via the isDelivered=true field.

image
image886Ă—425 21.2 KB

The second way has 3 steps and applies to cases where the ERP first sends only the information related to the order invoice, and then needs to update that information by adding tracking details in a later step. In this case, the following step-by-step process must be followed:

  1. Insert the invoice with billing information (without tracking information) through the Order invoice notification API. When invoicing is done referencing the order items, that information must also be sent at this point.
  2. Send the tracking code and other tracking information to the invoice already inserted in the previous step, using the Update order’s partial invoice (send tracking number) API.
  3. Continuously send tracking updates to our platform through the Update order tracking status API until the package has been delivered to the recipient and this is reported via the isDelivered=true field.

The parties responsible for making these requests are :red_circle: ERP and :articulated_lorry: Carrier. Considering the ideal flow:

  1. Insert invoice → :red_circle: ERP
  2. Send tracking information → :articulated_lorry: Carrier
  3. Send tracking updates → :articulated_lorry: Carrier

In order:

1. :page_facing_up: Order Invoice Notification [POST]

In our logs, this workflow is called NotifyInvoice.

This is the method that should be used by the :red_circle: ERP to insert the order billing information, where:

  • invoiceNumber is the order’s invoice number;

  • invoiceValue is the value of the order’s invoice. It is worth noting that for the order to move to Invoiced status, this value must match the total order value;

  • invoiceKey is the access key;

  • invoiceUrl is the invoice URL;

  • embededInvoice is the field where the order invoice XML must be inserted, and it is required for the order status to be updated in certified integration Marketplaces.

As a general rule, one request should be sent per invoice per order.

What happens if I send more than one NotifyInvoice for the same invoice?

Since this is a POST method, the previous invoice will be overwritten and information may be lost. The last update sent takes precedence.

2. :envelope_with_arrow: Update order’s partial invoice (send tracking number) [PATCH]

In our logs, this workflow is called UpdatePartialInvoice.

This is the method that should be used by the :articulated_lorry: carrier to insert the tracking and delivery information (as the name suggests), such as:

  • trackingNumber is the tracking code;

  • trackingUrl should be filled in with the tracking URL;

  • dispatchedDate is the dispatch date;

  • courier is the field dedicated to the carrier’s name.

As with the previous step, this data only needs to be sent once per invoice per order — unless it becomes necessary to update the tracking information that was sent (there is no need to use this method multiple times per invoice per order).

Since this is a PATCH method, only the tracking parameters of the invoice will be filled in — those that were left blank in the previous step’s request.

What happens if I send more than one UpdatePartialInvoice for the same invoice?

Since this API uses the PATCH method, only the parameters sent the second time will be overwritten. The other fields sent in the previous step remain unchanged.

3) :delivery_truck: Update order tracking status [PUT]

In our logs, this workflow is called UpdateTrackingStatus.

This is the method that should be used by the :articulated_lorry: carrier to insert tracking updates. It is worth noting that it can be used multiple times, until the order has actually been delivered to its final recipient, where:

  • isDelivered is the field that indicates whether the order has been delivered or not;

  • deliveredDate is the delivery date;

  • events is the array containing the location, date, and description of the updates.

Unlike the previous steps, multiple requests to this API are expected. Since this is a PUT method, each new update will be inserted into the order’s information under the courierStatus field. All updates sent are recorded — not just the most recent one — unlike the previous steps.

Important notes:

The NotifyInvoice resource is required to use this API request. It is included in the following access profiles: OMS - Full access and IntegrationProfile - Fulfillment Oms, among other standard roles available in the Admin. If you’d like to learn more, check out Roles.

Also, if you still have any questions on this topic, feel free to ask right here! :smiling_face:

Karina Mota
Field Software Engineer | VTEX

2

It’s important to note that for most marketplaces, the embededInvoice field with the XML is mandatory for the integration to work correctly.