[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] How do I use the VTEX facebook fbe app? Provide documentation and configuration details.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/vtex-io-apps)

Facebook Business Extension

Official extension

Version: 1.12.3

Latest version: 1.12.3

The [Facebook Business Extension and Conversions API app](https://read.calvincode.net/reader?url=https://apps.vtex.com/vtex-facebook-fbe/p) is the one-stop shop for merchants to easily connect their stores to Facebook services through the FBE platform. FBE stands for Facebook Business Extension and supports integration with Facebook features such as [Catalog](https://read.calvincode.net/reader?url=https://developers.facebook.com/docs/marketing-api/catalog), [Facebook Pixel](https://read.calvincode.net/reader?url=https://developers.facebook.com/docs/facebook-pixel), Conversions Api, and call-to-action buttons for Facebook and Instagram pages.

## Table of Contents

* [Facebook Business Extension](#facebook-business-extension)
   * [Table of Contents](#table-of-contents)
   * [Compatibility](#compatibility)
   * [Getting Started](#getting-started)
   * [Facebook Features](#facebook-features)
   * [Ads Plugin](#ads-plugin)
   * [Conversions API Integration](#conversions-api-integration)
         * [Optimizing your Conversions API setup](#optimizing-your-conversions-api-setup)
         * [Required Actions](#required-actions)
                  * [Step 1 - Create the Trigger](#step-1---create-the-trigger)
                  * [Step 2 - Create the Tag](#step-2---create-the-tag)
                  * [Step 2b - What if I already have other customizations in my Purchase Tag?](#step-2b---what-if-i-already-have-other-customizations-in-my-purchase-tag)
                  * [Step 3 - Publish your Changes](#step-3---publish-your-changes)
                  * [Step 4 - Test your Changes](#step-4---test-your-changes)
   * [Disconnecting from FBE](#disconnecting-from-fbe)
   * [User Consent](#user-consent)

## Compatibility

This app is fully compatible with IO stores and partially compatible with Legacy (or headless) stores.

| Features               | Legacy            | IO |
| ---------------------- | ----------------- | -- |
| Facebook Pixel         | ❌                 | ✅  |
| Conversions API        | ✅ (only purchase) | ✅  |
| Catalog Sync           | ✅                 | ✅  |
| Call-To-Action Buttons | ✅                 | ✅  |

This means legacy stores need to do a few extra steps to optimize their Pixel/Conversions API setup, which is explained in the later topics of this documentation.

This app is fully compatible with the [Facebook Pixel App](https://read.calvincode.net/reader?url=https://apps.vtex.com/vtex-facebook-pixel/p). FBE detects if you've selected the same pixel and replaces the Facebook Pixel App with its own Pixel App, which is tailored to work properly with Conversions API.

This app is fully compatible with the [Facebook Connector](https://read.calvincode.net/reader?url=https://help.vtex.com/pt/tracks/integracao-com-o-facebook--7h8KvIC4DbRRc8VlyJ8PFc/5OP69kHWKca01wLH0w10jX). When you configure FBE, if you already have the catalog sync configured, the Facebook Connector won't be impacted and will keep working as usual. Otherwise, FBE automatically configures the Facebook Connector to enable Catalog synchronization with Facebook.

This app is available in all countries as long as the used currency is supported by Facebook Ads. You can check an updated list of all supported currencies in this link: [Accepted Currencies for Facebook Ads](https://read.calvincode.net/reader?url=https://www.facebook.com/business/help/151451521590943?id=738655959856647)

## Getting Started

> _To configure the Facebook Business Extension and Conversions API app in the VTEX Admin, check out the documentation [Integration with Facebook Business Extension](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/integration-with-facebook-business-extension--2hS3ANSZ7vlHCcba4h7k8D/7JvybNGcBXxGKbVWjadKjt)._

After installing the [Facebook Business Extension and Conversions API app](https://read.calvincode.net/reader?url=https://apps.vtex.com/vtex-facebook-fbe/p), you can connect to your Facebook account through the Admin menu under `Marketplace -> Facebook`.

Region, currency settings, and the store URL will be automatically filled in, but you can double-check these settings and change them if needed.

Store URL, region, and currency settings are saved in order to correctly fire store events such as AddToCart and Purchase and to enable call-to-action buttons on your store's social media pages (Facebook, Instagram, etc)

![{"base64":"  ","img":{"width":2134,"height":1412,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":336673,"url":"https://user-images.githubusercontent.com/1629129/126334878-2405d70a-6d99-4cfc-97b1-8f16973acf1e.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/126334878-2405d70a-6d99-4cfc-97b1-8f16973acf1e.png)

Upon clicking the `Connect with Facebook` button, a popup is shown, and the user can log in to their business account and select their Facebook assets, such as the business page, the Facebook pixel, and the catalog to sync with VTEX products:

![{"base64":"  ","img":{"width":2170,"height":1455,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":581563,"url":"https://user-images.githubusercontent.com/1629129/122405529-83c82080-cf56-11eb-811b-b3242f121318.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/122405529-83c82080-cf56-11eb-811b-b3242f121318.png)

After confirming, you can check your integration status and the installed features, such as call-to-action buttons and catalog configuration:

![{"base64":"  ","img":{"width":1984,"height":1347,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":222672,"url":"https://user-images.githubusercontent.com/1629129/138358151-d323bf60-8da5-4300-8181-bf6d6820aa63.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/138358151-d323bf60-8da5-4300-8181-bf6d6820aa63.png)

The numbers along the statuses are the IDs for your selected assets.

If you need to, you can change the integration settings by clicking on `Integration Settings`:

![{"base64":"  ","img":{"width":2299,"height":1492,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":354597,"url":"https://user-images.githubusercontent.com/1629129/122405675-9fcbc200-cf56-11eb-893e-151533c5f43c.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/122405675-9fcbc200-cf56-11eb-893e-151533c5f43c.png)

When you connect through FBE, the business manager ID and catalog ID are filled automatically since these fields are already provided by the app, so no extra steps are required here unless you need to change the Product Display Name, Category Mapping, or the Trade Policy.

## Facebook Features

On the features card, it's possible to configure other Facebook features. Upon clicking on the "Configure Feature" button, a popup on Facebook will guide you through those extra settings:

![{"base64":"  ","img":{"width":2880,"height":1252,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":699477,"url":"https://user-images.githubusercontent.com/1629129/122405822-beca5400-cf56-11eb-8e6d-cd7a9bc0db11.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/122405822-beca5400-cf56-11eb-8e6d-cd7a9bc0db11.png)

These features are all provided by a custom Facebook UI and include, but are not limited to:

* **Page Surface Call to Action Button**: Adds a `Buy Now` button to your Facebook Page, which redirects to your store.
* **Instagram Call to Action Button**: Adds a `Buy Now` button to your Instagram Page, which redirects to your store.
* **Messenger Call to Action**: Adds a `Buy Now` button inside Messenger when a user is messaging the business.

## Ads Plugin

On the ads plugin cards, it's possible to manage your Facebook ads.

![{"base64":"  ","img":{"width":1940,"height":684,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":354803,"url":"https://user-images.githubusercontent.com/12246072/176775187-f48636de-8ffa-41c6-b839-18d316b15109.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12246072/176775187-f48636de-8ffa-41c6-b839-18d316b15109.png)

Upon clicking on the "Open Ads Insights" button, a popup will open with the metrics and performance of your ads.

![{"base64":"  ","img":{"width":1626,"height":1412,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":651024,"url":"https://user-images.githubusercontent.com/12246072/176775192-a6d9059a-eb9c-46e6-a78a-03ac25298975.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12246072/176775192-a6d9059a-eb9c-46e6-a78a-03ac25298975.png)

By clicking on the "Open Ads Creation" button, another popup will open with a lightweight interface for ads creation.

![{"base64":"  ","img":{"width":1632,"height":1412,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":1107707,"url":"https://user-images.githubusercontent.com/12246072/176775197-7bcbb463-6be0-4259-ad24-55ab97d16ef7.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/12246072/176775197-7bcbb463-6be0-4259-ad24-55ab97d16ef7.png)

## Conversions API Integration

Conversions API comes with the FBE App by default. It allows firing certain events directly from VTEX servers, ensuring the relevant data reaches Facebook independently from front-end implementations and/or network failures.

These are the supported events in the current version of this App:

| Event             | Facebook Pixel (Native) | Conversions API |
| ----------------- | ----------------------- | --------------- |
| Page View         | ✅                       | ✅               |
| Content View      | ✅                       | ✅               |
| Search            | ✅                       | ✅               |
| Add To Cart       | ✅                       | ✅               |
| Initiate Checkout | ✅                       | ✅               |
| Purchase          | ✅                       | ✅               |

This integration is configured automatically upon connecting your Facebook account. The CAPI integration works on any store (Legacy/IO), be sure to follow the next steps to ensure an optimal setup for your store.

### Optimizing your Conversions API setup

First off, you may need to do some extra steps depending on your current Facebook Pixel Configuration.

> **Facebook Pixel** is a piece of code for your ecommerce website that lets you measure, optimize, and build audiences for your ad campaigns. When someone visits your website and takes an action (for example, buying something), the Facebook pixel is triggered and reports this action.

The table below shows if any actions are required:

| Store        | Pixel Setup        | Actions Required? |
| ------------ | ------------------ | ----------------- |
| Legacy (CMS) | None               | Yes ⚠            |
| Legacy (CMS) | Google Tag Manager | Yes ⚠            |
| VTEX IO      | None               | No ✅              |
| VTEX IO      | Facebook Pixel App | No ✅              |
| VTEX IO      | Google Tag Manager | Yes ⚠            |

If no actions are required, you may skip the following subtopic.

### Required Actions

**1** \- Browser events need to be fired with the correct parameters in order to promote correct deduplication between browser and server events. In this case, we need to do this for the Purchase event.

> **What is Event Deduplication?** Facebook tries to deduplicate identical events sent through the Facebook pixel and the Conversions API when we work with a redundant setup.

> **A redundant setup** is when you send the same events through from both a browser pixel and Conversions API. This is the default setup used by this App.

> **What events will I be able to configure in this step?** For now, the only supported event for this step is the Purchase event. The other 5 (PageView, ViewContent, Search, AddToCart, and InitiateCheckout) are just supported by VTEX IO stores. These scripts for Legacy stores are on our implementation roadmap.

This is done through specific parameters that may be used to guarantee the events are the same. The two parameters we'll be configuring in this section are the _Event ID_ and the _Event Name_.

* **Event ID**: This ID uniquely identifies an event. In our purchase event, we're going to use orderId as the Event ID.
* **Event Name**: This is the type of the event being triggered. In our purchase event, we're going to go with 'Purchase'.

**2** \- Browser events must be initialized with the _external\_id_ parameter in order to correctly match the actor of the event (the end consumer). We'll use the _userProfileId_ as the _external\_id_

> **The userProfileId** is a unique ID that represents an end consumer of a store in the VTEX platform.

In order to do all that, the following steps need to be done in **Google Tag Manager** (or your tool of choice):

#### Step 1 - Create the Trigger

You may skip this step if you already fire Purchase events through your browser Pixel.

After accessing your Google Tag Manager workspace, ensure you have a trigger for the `orderPlaced` event. This event happens in the checkout confirmation page, whenever a purchase is completed.

In order to do so, click on `Triggers` in the lateral menu:

![{"base64":"  ","img":{"width":462,"height":553,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":31509,"url":"https://user-images.githubusercontent.com/1629129/137395017-fbc748fa-cd86-44c4-bcdc-8c76af6a882f.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/137395017-fbc748fa-cd86-44c4-bcdc-8c76af6a882f.png)

Create a trigger of type `Custom Event`, and set the event name to `orderPlaced`:

![{"base64":"  ","img":{"width":1845,"height":780,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":75374,"url":"https://user-images.githubusercontent.com/1629129/137395493-d891ebc0-34b1-4216-b95a-c6f4c8841a17.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/137395493-d891ebc0-34b1-4216-b95a-c6f4c8841a17.png)

Save the trigger.

#### Step 2 - Create the Tag

With your trigger configured, you need to create a tag to run the custom code required to fire the purchase event to Facebook. You can find an example implementation through the pixel snippets in the FBE App. Go to Marketplace -> Facebook on your VTEX Admin, then click on the `Purchase` button under Pixel Snippets:

![{"base64":"  ","img":{"width":1970,"height":1128,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":209347,"url":"https://user-images.githubusercontent.com/1629129/138329122-56e31139-6008-4a68-91d8-a905709905a0.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/138329122-56e31139-6008-4a68-91d8-a905709905a0.png)

> It's important to emphasize that Pixel Snippets are only available if the Pixel Toggle is disabled. VTEX IO stores with the toggle enabled have no need for any extra configuration to have an optimal setup.

Then all you need to do for now is click the copy button:

![{"base64":"  ","img":{"width":1649,"height":913,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":306956,"url":"https://user-images.githubusercontent.com/1629129/138329453-b6aeef3d-aacf-4b09-86d1-e28f0c335b90.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/138329453-b6aeef3d-aacf-4b09-86d1-e28f0c335b90.png)

This snippet contains all the required parameters to trigger the purchase event correctly. **However, if you already have other kinds of customizations in your Purchase Tag, please read the next subtopic for more information about how the snippet was created so you can customize it according to your needs.**

Back on Tag Manager, create a new "Custom HTML" tag and paste the currently copied script into the HTML text box.

Click on "Triggering" and set the trigger to your "Order Placed" event:

![{"base64":"  ","img":{"width":1774,"height":1241,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":348631,"url":"https://user-images.githubusercontent.com/1629129/138329789-006ed605-bb60-4ff0-ba48-b95e590aee50.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/138329789-006ed605-bb60-4ff0-ba48-b95e590aee50.png)

Save your new tag.

#### Step 2b - What if I already have other customizations in my Purchase Tag?

This section is for setups that already have customizations in their Purchase Tag (such as detecting different payment methods or having additional parameters on the event payload besides `contents`, `contentId`, `contentType`, `currency`, and `value`)

Please be aware that this section is very technical since it explains in detail how exactly the Tag gathers all required information to compose and send the purchase event to Facebook.

(Click to Expand) This is the un-minified version of the Purchase Tag Snippet, explained:

`` 1

const pixelId = 111111111111 // this is your PixelId

2

3

// Function to convert an array buffer to its hexadecimal representation.

4

function buf2hex(buffer) {

5

 return Array.prototype.map

6

 .call(new Uint8Array(buffer), function (x) {

7

 return `00$\{x.toString(16)\}`.slice(-2)

8

 })

9

 .join('')

10

}

11

12

// Function that hashes values before sending them to FB.

13

function hashSHA256(value) {

14

 const encoder = new TextEncoder()

15

 const data = value ? encoder.encode(value) : Promise.resolve(undefined)

16

17

 const hashedValue = data

18

 ? window.crypto.subtle.digest('SHA-256', data).then(function (f) {

19

 return buf2hex(f)

20

 })

21

 : Promise.resolve(undefined)

22

23

 return hashedValue

24

}

25

26

// This is the main Pixel Code provided by Facebook.

27

!(function (f, b, e, v, n, t, s) {

28

 if (f.fbq) return

29

 n = f.fbq = function () {

30

 n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments)

31

 }

32

33

 if (!f._fbq) f._fbq = n

34

 n.push = n

35

 n.loaded = !0

36

 n.version = '2.0'

37

 n.queue = []

38

 t = b.createElement(e)

39

 t.async = !0

40

 t.src = v

41

 s = b.getElementsByTagName(e)[0]

42

 s.parentNode.insertBefore(t, s)

43

})(window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js')

44

45

// A small timeout of half a second is placed to ensure the fbq function is correctly loaded.

46

setTimeout(function () {

47

48

 // As this tag is self-containing, instead of using variables it peeks into the dataLayer by itself.

49

 const orderPlaced = dataLayer.find(function (d) {

50

 return d.event === 'orderPlaced'

51

 })

52

53

 // The UserProfile function retrieves the end consumer email from visitorContactInfo and calls the Checkout API to get the saved userProfile, which contains the userProfileId.

54

 // The userProfileId is used as the external_id which is an advanced matching parameter as described by Facebook.

55

 // visitorContactInfo is an array with 3 elements, composed by ['email', 'firstName', 'lastName']. We just need the email for now.

56

 const userProfile =

57

 orderPlaced &&

58

 orderPlaced.visitorContactInfo &&

59

 orderPlaced.visitorContactInfo.length > 0

60

 ? fetch(

61

 `/api/checkout/pub/profiles?email=$\{orderPlaced.visitorContactInfo[0]\}`

62

 )

63

 // Retrieve the response text from the API call.

64

 .then(function (f) {

65

 return f.text()

66

 })

67

 // Parse the response text as an Object.

68

 .then(function (f) {

69

 return JSON.parse(f)

70

 })

71

 // The e-mail and userProfileId must be hashed before they're sent to Facebook.

72

 // In no circunstance these parameters can be sent openly before hashing. If that happens, FB automatically discards them.

73

 .then(function (f) {

74

 return Promise.all([

75

 hashSHA256(f.userProfileId),

76

 hashSHA256(orderPlaced.visitorContactInfo[0].toLowerCase()),

77

 ])

78

 })

79

 : Promise.resolve([])

80

81

 // With the userProfile in hands, we're able to compose the advancedMatchingParams

82

 userProfile.then(function (profileInfo) {

83

 const advancedMatchingParams =

84

 profileInfo.length == 2 && profileInfo[0] && profileInfo[1]

85

 ? {

86

 external_id: profileInfo[0],

87

 em: profileInfo[1],

88

 }

89

 : {}

90

91

 // This condition checks if fbq was already loaded/executed in this page.

92

 if (!fbq.instance.pixelsByID[pixelId]) {

93

 // Here we initialize the Pixel with the Advanced Matching Parameters.

94

 fbq('init', String(pixelId), advancedMatchingParams, { agent: 'vtex' })

95

96

 // Then we track the PageView

97

 fbq('track', 'PageView')

98

 }

99

100

 // The Event ID should always be the orderGroupId without -01, -02, etc, to match the Event ID from Conversions API.

101

 var substr = orderPlaced.transactionId.indexOf('-');

102

 var orderId = orderPlaced.transactionId.substring(0, substr > 0 ? substr : orderPlaced.transactionId.length);

103

104

 // After that, we create the PurchaseEvent object based on the order placed.

105

 const eventObject = {

106

 value: orderPlaced.transactionTotal,

107

 content_type: 'product',

108

 currency: orderPlaced.transactionCurrency,

109

 content_ids: orderPlaced.transactionProducts.map(function (p) {

110

 return p.sku

111

 }),

112

 contents: orderPlaced.transactionProducts.map(function (p) {

113

 return { id: p.sku, quantity: p.quantity, price: p.sellingPrice }

114

 }),

115

 }

116

117

 // In order to ensure deduplication, we send the orderId as the eventID, and the event as 'Purchase'.

118

 // This works perfectly for the purchase event since the orderId is unique.

119

 const eventParams = {

120

 eventID: orderId,

121

 event: 'Purchase',

122

 }

123

124

 // We can finally track the Purchase event

125

 fbq('track', 'Purchase', eventObject, eventParams)

126

 })

127

}, 500)

 ``

#### Step 3 - Publish your Changes

After saving your tag, you need to submit and publish your new version.

#### Step 4 - Test your Changes

You can then test your events on the Events Manager on the Facebook platform. Open the test events tab and fill in your store URL. Click on the button to open a new browser and finish a purchase in your store. All events should show up in the Test Events Tab:

![{"base64":"  ","img":{"width":1997,"height":1229,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":263344,"url":"https://user-images.githubusercontent.com/1629129/122405892-cc7fd980-cf56-11eb-96ac-ae304d9f9edd.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/122405892-cc7fd980-cf56-11eb-96ac-ae304d9f9edd.png)

> Though most of the setups use GTM to fire pixel events, it's possible to configure this using other tools. Just make sure the corresponding parameters are being sent correctly in your tool of choice.

## Disconnecting from FBE

At any point in time, the user can disconnect from FBE. Please note that while disconnecting revokes access from the system user created for the integration, it does not stop catalog synchronization either. In order to disable it, deactivate catalog sync on the find marketplaces (`/admin/marketplace-configuration/facebook`) settings.

Be aware that upon disconnecting, the app will stop sending pixel events (pixel and conversions API). It will resume working as expected if you reconnect to FBE.

Previous Facebook Pixel (`vtex.facebook-pixel`) installations that might have been uninstalled during FBE configuration will also be reinstalled.

![{"base64":"  ","img":{"width":2304,"height":1482,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":168522,"url":"https://user-images.githubusercontent.com/1629129/122410321-3188fe80-cf5a-11eb-8896-a191a326dd11.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/1629129/122410321-3188fe80-cf5a-11eb-8896-a191a326dd11.png)

## User Consent

This functionality must be associated with a third-party cookie consent system. To enable the blocking of pixel and server events (with the exception of the server event for the purchase), you must activate the flag through the settings in the admin (`/admin/apps/vtex.facebook-fbe@1.x/setup/`):

![{"base64":"  ","img":{"width":2728,"height":1226,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":208451,"url":"https://user-images.githubusercontent.com/67066494/227299562-e824a028-118e-4efc-a63f-18cddca9c8b1.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/67066494/227299562-e824a028-118e-4efc-a63f-18cddca9c8b1.png)

After activating this functionality, the Facebook script will be initialized with consent revoke, as documented by Facebook in the following article:<https://developers.facebook.com/docs/meta-pixel/implementation/gdpr>

In addition, a cookie is created called fbe\_consent set to false, preventing events via the server. To allow the emission of events after the user's consent, the `fbq` function must be called, as well as the cookie value must be changed through a script implemented by the store within the third-party tool:

`1

fbq('consent', 'grant')

2

document.cookie = "fbe_consent=true"

`

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Table of Contents](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23table-of-contents)

[Compatibility](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23compatibility)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23getting-started)

[Facebook Features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23facebook-features)

[Ads Plugin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23ads-plugin)

[Conversions API Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23conversions-api-integration)

[Optimizing your Conversions API setup](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23optimizing-your-conversions-api-setup)[Required Actions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23required-actions)

[Disconnecting from FBE](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23disconnecting-from-fbe)

[User Consent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.facebook-fbe/docs/apps/vtex.facebook-fbe%23user-consent)

Was this helpful?

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides integration vtex sales app local stock sale in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

[How to customize VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/how-to-customize-vtex-sales-app)

[Change VTEX Sales App language](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/change-vtex-sales-app-language)

[Hide anonymous customer option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/hide-anonymous-customer-option)

[Define payment methods displayed on VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/define-payment-methods-displayed-on-vtex-sales-app)

[Enable the Observation field in the order screen](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/enable-the-remarks-field-in-the-order-screen)

[Enable the sales associate code](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/sales-associate-code)

[Enable cart transfer and capture between devices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/enable-cart-transfer-between-devices)

[Force stock availability](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/force-stock-availability)

[Add extra text to the order summary print](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/add-extra-text-to-the-order-print)

[Hide Print order and Reprint receipt buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/hide-print-order-and-reprint-receipt-buttons)

[Enable partial cancellation for Debit or Credit Direct sales](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/enable-partial-cancellation)

[Hide cancellation buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/hide-cancellation-buttons)

[Allow manual prices on VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/allow-manual-prices-on-vtex-sales-app)

[Integration VTEX Sales App Local stock sale](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale)

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

[How to customize VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/how-to-customize-vtex-sales-app)

[Change VTEX Sales App language](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/change-vtex-sales-app-language)

[Hide anonymous customer option](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/hide-anonymous-customer-option)

[Define payment methods displayed on VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/define-payment-methods-displayed-on-vtex-sales-app)

[Enable the Observation field in the order screen](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/enable-the-remarks-field-in-the-order-screen)

[Enable the sales associate code](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/sales-associate-code)

[Enable cart transfer and capture between devices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/enable-cart-transfer-between-devices)

[Force stock availability](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/force-stock-availability)

[Add extra text to the order summary print](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/add-extra-text-to-the-order-print)

[Hide Print order and Reprint receipt buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/hide-print-order-and-reprint-receipt-buttons)

[Enable partial cancellation for Debit or Credit Direct sales](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/enable-partial-cancellation)

[Hide cancellation buttons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/hide-cancellation-buttons)

[Allow manual prices on VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/allow-manual-prices-on-vtex-sales-app)

[Integration VTEX Sales App Local stock sale](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale)

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides)

VTEX Sales App

[How to customize VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/how-to-customize-vtex-sales-app)

[Integration VTEX Sales App Local stock sale](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale)

Integration VTEX Sales App Local stock sale

Learn how to integrate the VTEX Sales App Local stock sale

## Integration VTEX Sales App Local stock sale

To first identify Local stock sale sales the first thing to do is to look for [VTEX Sales App](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/instore-getting-started-and-setting-up--zav76TFEZlAjnyBVL5tRc/7fnnVlG3Kv1Tay9iagc5yf) sales. VTEX Sales App sales can be filtered by a specific OMS filter called "VTEX Sales App", this filter looks for user agent information that sets a specific user agent that can be used to track VTEX Sales App sales. This tag is not available at the Order Payload or databases (redshift), but it can be used at [list orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/listorders) to filter VTEX Sales App Sales. Another field that can be used for this is `marketingData.marketingTags`, if the array contains an "VTEX Sales App" tag the order was made by VTEX Sales App application. This field can be found at the Order Payload and Redshift databases.

The next step is to understand if the order generated will be processed by the same store that has created it. To do that, check first if the `checkedIn` flag is `true`, next run through all products of this order looking at `shippingData.logisticsInfo`. Inside this key, it is needed to compare `pickupPointId` with `checkedInPickupPointId` the value of those tags must be the same and not null, meaning that the store that created the order is responsible for delivering the order.

## Integration Methods

Now that VTEX Sales App Orders and _"Local stock sale delivery method"_ can be identified in our OMS, the next step is to use the available methods to consume OMS APIs to process Local stock sale orders. There are two options for that:

### Tracking Local stock sale Order

The Local stock sale Order tracking can be active or passive regarding what works best for the business. Although we strongly recommend to use **Web Hook Integrations** for Physical Stores Sales Operations, since it provides the best response time.

### API Integration

It is recommended to get a list from all On Hand Orders in a specific time gap. You can use this method to display all Local stock sale orders or to double check the orders and reprocess any of it that had issues for invoicing or updating the ERP / POS inventory. Although it is not recommended to track orders using this method, for that it is needed to integrate by Web Hook APIs.

As an example you can use this request:

`1

curl --request GET \

2

 --url 'https://accountname.environment.com.br/api/oms/pvt/orders?f_creationDate=creationDate%3A%5B2016-01-01T02%3A00%3A00.000Z%20TO%202021-01-01T01%3A59%3A59.999Z%5D&f_hasInputInvoice=false&f_isInstore=true' \

3

 --header 'Accept: application/json' \

4

 --header 'Content-Type: application/json'

`

This is a normal request using the Get Orders List method by OMS API. To filter VTEX Sales App orders it is needed to set the flag **f\_isInstore=true.** Then to know if it is an Local stock sale Orders check if the flag **checkedInPickupPointId is not null** and compare the value of it is equal to the tag **shippingData.logisticsInfo.pickupPointId** on every product.

### Web Hook Integration

First, it is necessary to configure a web hook to receive Local stock sale orders. For this it can be used the following expression, inside the filter tag ([Order Hooks Documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/orders-feed%23configuration-1)):

`1

{

2

 "filter": {

3

 "type": "FromOrders",

4

 "expression": "(\"instore\" in marketingData.marketingTags) and (checkedInPickupPointId != null) and (checkedInPickupPointId in shippingData.logisticsInfo[].pickupPointId)",

5

 "disableSingleFire": false

6

 },

7

 "hook": {

8

 "url": "https://endpoint.example/path",

9

 "headers": {

10

 "key": "value"

11

 }

12

 }

13

}

`

As response of this configuration, the endpoint used at the example before is going to receive the following payload when a new Local stock sale order is placed ([Order Hooks documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/orders-feed%23hook-notifications)):

`1

{

2

 "Domain": "OrdersDocumentUpdated",

3

 "OrderId": "v40484048naf-01",

4

 "State": "unknow",

5

 "LastState": null,

6

 "LastChange": "2022-12-15T20:32:06.6120711",

7

 "CurrentChange": "0001-01-01T00:00:00",

8

 "Origin": {

9

 "Account": "accountABC",

10

 "Key": "vtexappkey-keyEDF"

11

 }

12

}

`

The received order id can be used to get the full Order information, including the products on it by using the OMS API Method: Get Order ([Orders API reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/getorder)).

### Invoicing Local stock sale Order

After getting the Order Data, the next step is to start an Invoice Emission, this step is not handled by VTEX and each Merchant can pick the solution that fits best their operation (ie: using POS software to emit and print it at the physical store, using ERP to send it through email…).

Regardless of the solution adopted to emit the invoice, one important thing is to attach the invoice data into the VTEX OMS system. By this, VTEX Sales App can inform the sales associate that the order invoice was invoiced. To do that, it can be used the following OMS resource sending an payload as the example below ([Order Invoice API reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/invoicenotification)):

`1

{

2

 "type": "Output",

3

 "invoiceNumber": "NFe-00001",

4

 "courier": "",

5

 "trackingNumber": "",

6

 "trackingUrl": "",

7

 "items": [

8

 {

9

 "id": "345117",

10

 "quantity": 1,

11

 "description": "335",

12

 "price": 9003

13

 }

14

 ],

15

 "issuanceDate": "2013-11-21T00:00:00",

16

 "invoiceValue": 9508

17

}

`

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F25390429%3Fv%3D4%26w=64%26q=75)](https://github.com/karenkrieger)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/VTEX-Sales-App/integration-vtex-sales-app-local-stock-sale.md)

[Allow manual prices on VTEX Sales App« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale//docs/guides/allow-manual-prices-on-vtex-sales-app)[My AuthenticationNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale//docs/guides/ui-customization-my-authentication)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F25390429%3Fv%3D4%26w=64%26q=75)](https://github.com/karenkrieger)

ON THIS PAGE

[Integration VTEX Sales App Local stock sale](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23integration-vtex-sales-app-local-stock-sale)

[Integration Methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23integration-methods)

[Tracking Local stock sale Order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23tracking-local-stock-sale-order)[API Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23api-integration)[Web Hook Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23web-hook-integration)[Invoicing Local stock sale Order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23invoicing-local-stock-sale-order)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/VTEX-Sales-App/integration-vtex-sales-app-local-stock-sale.md)

Copy page

On this page

ON THIS PAGE

[Integration VTEX Sales App Local stock sale](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23integration-vtex-sales-app-local-stock-sale)

[Integration Methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23integration-methods)

[Tracking Local stock sale Order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23tracking-local-stock-sale-order)[API Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23api-integration)[Web Hook Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23web-hook-integration)[Invoicing Local stock sale Order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/integration-vtex-sales-app-local-stock-sale/docs/guides/integration-vtex-sales-app-local-stock-sale%23invoicing-local-stock-sale-order)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides formatting order invoicing time in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/master-data)

---

Payments

---

Orders

[Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/orders-feed)

[Order modifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/order-modifications)

[Change seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/change-seller)

[Cancel order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/order-canceling-improvements)

[Actions in orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/actions-orders)

[Fetching marketplace information with the Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/get-marketplace-data-orders-api)

[Fetching payment details from a Mercado Libre order with Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/get-payment-data-mercado-libre-orders-api)

[Formatting order invoicing time via API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/formatting-order-invoicing-time)

[Using VTEX Admin filters on orders via API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/using-orders-management-filters-in-api)

[Adding a second address for invoicing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/adding-a-second-address-to-the-order)

Subscriptions

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/master-data)

---

Payments

---

Orders

[Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/orders-feed)

[Order modifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/order-modifications)

[Change seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/change-seller)

[Cancel order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/order-canceling-improvements)

[Actions in orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/actions-orders)

[Fetching marketplace information with the Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/get-marketplace-data-orders-api)

[Fetching payment details from a Mercado Libre order with Orders API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/get-payment-data-mercado-libre-orders-api)

[Formatting order invoicing time via API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/formatting-order-invoicing-time)

[Using VTEX Admin filters on orders via API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/using-orders-management-filters-in-api)

[Adding a second address for invoicing an order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/adding-a-second-address-to-the-order)

Subscriptions

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides)

Orders

[Actions in orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/actions-orders)

[Formatting order invoicing time via API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/docs/guides/formatting-order-invoicing-time)

Formatting order invoicing time via API

When submitting invoice data to a marketplace via API, you can use the endpoint [Update order's partial invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/updatepartialinvoicesendtrackingnumber) to format the order invoicing time. The correct JSON format for the request is as the following example:

`1

{

2

 "type":"Output",

3

 "issuanceDate":"2017-10-05T11:32:11",

4

 "invoiceNumber":"9999",

5

 "invoiceValue":"10000",

6

 "invoiceKey": null,

7

 "invoiceUrl": null,

8

 "courier": null,

9

 "trackingNumber": null,

10

 "trackingUrl": null,

11

 "items": [

12

 {

13

 "id": "1234",

14

 "price": 10000,

15

 "quantity": 1

16

 }

17

 ]

18

 }

`

The property responsible for informing the invoicing date and time is `issuanceDate`. This field follows the UTC 0 time zone.

If you want to include a time with a specific time zone (for example: "UTC -3"), you must use a format like the example below:

`"issuanceDate": "2017-10-05T11:32:11-0300"`

**Attention:** Do not use any spaces on the date.

Note that integrations that fetch order data from the VTEX system should also be aware of the time zone and make the necessary adjustments.

For details on how the request should be formatted, see the API [Update order's partial invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/updatepartialinvoicesendtrackingnumber).

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Orders/actions-orders/formatting-order-invoicing-time.md)

[Fetching payment details from a Mercado Libre order with Orders API« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time//docs/guides/get-payment-data-mercado-libre-orders-api)[Using VTEX Admin filters on orders via APINext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time//docs/guides/using-orders-management-filters-in-api)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/formatting-order-invoicing-time/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Orders/actions-orders/formatting-order-invoicing-time.md)

Copy page

On this page

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides calling commerce apis 2 discovering vtex commerce apis and authentication in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-on-vtex-io)

[1\. Getting the Service app boilerplate](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-1-getting-the-service-app-boilerplate)

[2\. Discovering VTEX Commerce APIs and authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication)

[3\. Using VTEX IO clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-3-using-vtex-io-clients)

[Calling Commerce APIs - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-conclusion)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-getting-started)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/app-development-guides)

[Services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-service)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-on-vtex-io)

[1\. Getting the Service app boilerplate](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-1-getting-the-service-app-boilerplate)

[2\. Discovering VTEX Commerce APIs and authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication)

[3\. Using VTEX IO clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-3-using-vtex-io-clients)

[Calling Commerce APIs - Conclusion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-conclusion)

[Clients](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-clients)

Handling events

[Path patterns](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/service-path-patterns)

[Configuring dynamic routes in VTEX IO services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/configuring-dynamic-routes-in-vtex-io-services)

[Developing service configuration apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-developing-service-configuration-apps)

[Node builder 7.x migration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/node-builder-7x-migration-guide)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/app-development)

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/app-development-guides)

[Calling commerce APIs on VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-on-vtex-io)

[2\. Discovering VTEX Commerce APIs and authentication](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication)

2\. Discovering VTEX Commerce APIs and authentication

Now that we have a comprehensive understanding of the project structure, it's important to address API authentication before we proceed with calling VTEX Core Commerce APIs. VTEX strongly advises against using the `AppKey` and `AppToken` pair in VTEX IO apps. Instead, the recommended practice involves utilizing the VTEX ID token.

Every app developed on VTEX IO represents a resource on the platform. This allows an app to interact with other systems on behalf of itself, duly authorized by the account administrator. It is the reponsibility of the app developer to declare the necessary permissions. In practical terms, this entails:

* Declaring both the endpoint and the [roles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-roles) required to access any API in the apps's `manifest.json` file.
* Making request with a **VTEX ID token** instead of the **AppKey** and **AppToken** pair. For more information, refer to [App authentication using auth tokens](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens).

## Logging the app token

Each VTEX IO app is issued a corresponding `authToken`. This token can be obtained from the `ctx` object and contains all the permissions declared in the `policies` field of the app's `manifest.json` file.

To inspect the `authToken` of an app, go to the `node/middlewares/validate.ts` file and add the highlighted log code.

## Checking the app token

With the app linked to your development workspace, access the service route and check the content logged in the terminal. Use the following URL format: `https://{workspace}-{account}.myvtex.com/_v/status/:code`, replacing `{workspace}` and `{account}` according to your scenario, and `:code` with `200`

## Decoding the app token

Check the content of this token using a platform such as [jwt.io](https://read.calvincode.net/reader?url=https://jwt.io/). This decoded representation provides valuable details, including the associated account and workspace, user and role information, as well as timestamps for token validity.

node/middlewares/validate.ts

`1

import { UserInputError } from '@vtex/api'

2

3

export async function validate(ctx: Context, next: () => Promise<any>) {

4

 const {

5

 vtex: {

6

 route: { params },

7

 },

8

 } = ctx

9

10

 console.log(ctx.vtex.authToken)

11

 console.info('Received params:', params)

12

13

 const { code } = params

14

15

 if (!code) {

16

 throw new UserInputError('Code is required') // Wrapper for a Bad Request (400) HTTP Error. Check others in https://github.com/vtex/node-vtex-api/blob/fd6139349de4e68825b1074f1959dd8d0c8f4d5b/src/errors/index.ts

17

 }

18

19

 const codeNumber = parseInt(code as string, 10)

20

21

 ctx.state.code = codeNumber

22

23

 await next()

24

}

`

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Calling Commerce APIs/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication.mdx)

[1\. Getting the Service app boilerplate« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication//docs/guides/calling-commerce-apis-1-getting-the-service-app-boilerplate)[3\. Using VTEX IO clientsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication//docs/guides/calling-commerce-apis-3-using-vtex-io-clients)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Logging the app token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication%23logging-the-app-token)

[Checking the app token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication%23checking-the-app-token)

[Decoding the app token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication%23decoding-the-app-token)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Calling Commerce APIs/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication.mdx)

Copy page

On this page

ON THIS PAGE

[Logging the app token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication%23logging-the-app-token)

[Checking the app token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication%23checking-the-app-token)

[Decoding the app token](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication/docs/guides/calling-commerce-apis-2-discovering-vtex-commerce-apis-and-authentication%23decoding-the-app-token)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)