{"section":"tutorials","requestedLocale":"en","requestedSlug":"master-data","locale":"en","slug":"master-data","path":"docs/en/tutorials/master-data/master-data-basics/master-data.md","branch":"main","content":"Master Data is a VTEX database platform solution, which is highly customizable, and it also enables you to create applications.\n\nBy default, Master Data is used to store and organize Customer data from your store. It features a powerful search engine, allowing you to store, search, expand, and customize data.\n\nIn this article you will learn more about each available version of the Master Data, important concepts, and how to use it.\n\n> ℹ️ Note that depending on the functionality and version you wish to use, it is necessary to contact your development team.\n\n## Versions available\n\nCurrently there are two versions available and you can choose the one that best suits your operational needs. The main difference between the two is that v2 does not have a graphical interface and can be used only through [Master Data v2 API](https://developers.vtex.com/docs/api-reference/master-data-api-v2), although it has other relevant functionalities, such as the use of [JSON schemas](https://developers.vtex.com/docs/guides/starting-to-work-on-master-data-with-json-schema).\n\n> ℹ️ VTEX automatically saves customer data from your store in Master Data v1.\n\nCheck the table below to learn more about the different functionalities of each version.\n\n| Functionality | v1 | v2 | Learn more |\n|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Graphical interface | Yes | No | - |\n| API | Yes | Yes | - [Master Data v1 API](https://developers.vtex.com/docs/api-reference/masterdata-api)
- [Master Data v2 API](https://developers.vtex.com/vtex-rest-api/reference/master-data-api-v2-overview) |\n| Importing and exporting spreadsheets | Yes | No | - [Import data into Master Data v1](/en/tutorial/importing-data-into-master-data--tutorials_1135#)
- [Export data from Master Data v1](/en/tutorial/exporting-data--tutorials_1125#) |\n| Attachments (imagens) | Yes | No | - |\n| Triggers | Yes | Yes | - [Triggers](#triggers)
- [Creating triggers with Master Data v1](/en/tutorial/creating-trigger-in-master-data--tutorials_1270#)
- [Creating triggers with Master Data v2](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2) |\n| JSON Schemas | No | Yes | - [JSON schemas](http://json-schema.org/)
- [Understanding JSON schemas](https://json-schema.org/understanding-json-schema)
- [Starting to work with JSON schemas in Master Data v2](https://developers.vtex.com/vtex-rest-api/docs/starting-to-work-on-master-data-with-json-schema)
- [Schema life cycle in Master Data v2](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle) |\n| Nested properties | No | Yes | - [Nested properties](#nested-properties) |\n| Data entities | Referenced by acronyms composed of two capital letters. For example, the 'CL' entity stores client data from the store and 'AD' stores addresses. Cannot be created via API. | Referenced by their names. For example, 'Notification'. Can only be created via API. | - [Data entities](#data-entities)
- [Data entities in Master Data v1](/en/docs/tutorials/data-entity)
- [Creating relationships between Master Data v2 data entities](https://developers.vtex.com/vtex-rest-api/docs/creating-relationships-between-data-entities-using-api) |\n| Fields | Must be filled in in the specific format configured in the data entity. | At first, there is no restriction on fields's formats. Format is validated through JSON schemas. | - [Field types in Master Data v1](/en/docs/tutorials/data-entity#understanding-the-types)
- [JSON schemas](#v2-schemas) |\n| Indexes | Yes | Yes | - [How to set up indexes in Master Data v1](/en/docs/tutorials/indexes-in-master-data)
- [How to set up indexes with Master Data v2 API](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) |\n\n> ❗ Note that the data entities of the two versions are independent, even if some may be analogous. This means that a data created in a v1 entity cannot be queried or edited using v2 resources and vice versa.\n\n## Basic components\n\nBoth versions of Master Data use some basic components, which may be equivalent to concepts found in other database solutions, with other names such as record or table. Below you can find more details about:\n\n- [Data entities](#data-entities)\n- [Documents](#documents)\n- [Fields](fields)\n- [Indexes](#indexes)\n\n### Data entities\n\nData entities are in the form of tables where documents and fields are recorded.\n\nMaster Data v1 data entities are referenced by acronyms composed of two capital letters. In v2, you can use the name of the data entity. For example, in v1, the 'CL' entity stores Client data from the store and 'AD' stores client addresses. Equivalent entities in v2 can be referenced with names such as 'Client' and 'Address'.\n\nIn a data entity date, the information is structured in [documents](#documents) and [fields](#fields).\n\n### Documents\n\nDocuments are records in a data entity. If data entities are in the form of tables, each document represents a row in a table.\n\nFor example, within an entity that stores client data from the store, such as 'CL' or 'Client', each document contains information from a client.\n\nEach document has an ID automatically generated by the platform at the time of its creation, a unique code that identifies that record.\n\n### Fields\n\nThe attributes that make up Master Data documents are called fields. When comparing data entities with tables, we can think of the fields as the columns of a table.\n\nFor example, in an entity that stores client data from the store, such as 'CL' or 'Client', we may fill in fields such as **name**, **email**, **date of birth**, and **document**.\n\nIn Master Data v1, the fields must be filled in in the specific format configured in the data entity. Learn more about [the field types in Master Data v1](/en/docs/tutorials/data-entity#entendendo-os-tipos).\n\nHowever, in v2, there is no restriction on fields and formats. Format validation is made through [JSON schemas](#v2-schemas).\n\n#### Nested properties\n\nMaster Data v2 allows you to structure the data with nested properties, a structure often found in the [JSON](https://www.json.org/json-en.html) format. This concept consists of the possibility of creating composite fields from other fields, to better structure the data. For example, a client profile might have the field 'Document', which in turn consists of the 'Type' and 'Number' properties. You can also create nested [triggers](#triggers).\n\n### Indices\n\nIndices are used to specify a document to be accessed, indicated by an indexed field instead of its ID.\n\nAs mentioned above, each document has an ID automatically generated by the platform at the time of its creation. If you want to query a document but do not know its ID, you can use indices.\n\nFor example, you can query a document with a client's information by specifying the value of the 'email' field for the client.\n\n> ℹ️ Learn more about [setting up indexes in Master Data v1](/en/docs/tutorials/indexes-in-master-data) or [setting up indexes with Master Data v2 API](https://developers.vtex.com/vtex-rest-api/reference/putindices).\n\n## Triggers\n\nA Master Data trigger is a mechanism that performs an action after creating or updating a document, if the conditions set in the configuration are met. These actions can be of three types:\n- Send HTTP request.\n- Send an email.\n- Save document in another data entity.\n\nLearn more about how [to configure triggers in Master Data v1](/en/docs/tutorials/creating-trigger-in-master-data) or how [to configure triggers with Master Data v2 API](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2)\n\n## v2 schemas\n\nWith Master Data v2, you can define data formats with JSON schemas. This format indicates how the Master Data should validate and index documents.\n\n> ℹ️ Learn more about [JSON schemas](https://json-schema.org/).\n\nYou can save a document to any data entity if the content is a valid JSON. A data entity may or may not have multiple JSON schemas associated with it.\n\n\n\n> ℹ️ A document can be compatible with multiple JSON Schemas, but also with none.\n\n## Master Data native entities\n\nSome data entities are automatically created by VTEX to support native platform features.\n\n### Master Data v1 native entities\n\n| **Entity** | **Description** |\n|----------|--------|\n| `cl` | Customer accounts (clients) |\n| `ad` | Customer addresses |\n| `bk` | Bucket (generic key/value) |\n| `gc` | Gift cards |\n| `gt` | Gift card constraints |\n| `il` | Internal logs |\n| `iw` | Internal warnings |\n| `rd` | Order (mirror) |\n| `od` | Orders |\n| `so` | Stores |\n| `iy` | Availability item |\n| `au` | Audit log |\n| `sb` | BridgeOrderSeller |\n| `bx` | Buzz extract |\n| `bb` | Buzz billing |\n| `bo` | BridgeOrder |\n| `mb` | BridgeOrderMarketplace |\n| `hl` | Holidays |\n| `AS` | Availability Notifier (most likely source) |\n| `LOG` | PayU Europe PPP |\n| `AE` | Avatax BR (Tax Protocol + Service) |\n| `AL` | Avatax BR Service |\n| `CS` | Casino Gift Card |\n| `SP` | Middleware Smiles Checkout |\n\n### Master Data v2 native entities\n\n| **Entity** | **Description** |\n|----------|--------|\n| `account` | Digital Currency |\n| `affiliates` | Affiliates |\n| `affiliatesOrders` | Affiliates Commission Service |\n| `audit` | v2 Audit entity |\n| `b2b_profiles` | Storefront Permissions |\n| `b2b_quote_marketplace` | b2b_quote_marketplace |\n| `b2b_roles` | Storefront Permissions |\n| `b2b_seller_quote` | b2b_seller_quote |\n| `b2b_users` | Storefront Permissions (owner) |\n| `badges` | Badges |\n| `business` | Sales Autopilot Service |\n| `BusinessOrganization` | Easy Setup (legacy B2B seeder) |\n| `BusinessPermission` | Easy Setup (legacy B2B seeder) |\n| `BusinessRole` | Easy Setup (legacy B2B seeder) |\n| `buyerOrgConfiguration` | VTEX B2B Core |\n| `buyerOrgMember` | VTEX B2B Core |\n| `campaigns` | Opt-in Campaign Service (shared with Opt-in Campaign Listener) |\n| `CANCEL_ORDER_FISCAL_CODE` | Order SMS Notification |\n| `charge` | Digital Currency |\n| `checkoutcustom` | Checkout UI Custom |\n| `commissionBySKU` | Affiliates Commission Service |\n| `commissioninvoices` | Mktplace Financial Commissions |\n| `contact_information` | contact_information |\n| `cost_centers` | B2B Organizations GraphQL |\n| `creditAccount` | Digital Currency |\n| `custom_prices` | Custom Prices (B2B) |\n| `customFieldSettings` | v2 custom field settings |\n| `customFieldValues` | v2 custom field values |\n| `defaultValues` | defaultValues |\n| `eventinfo` | Worldline Global Collect |\n| `eventRegistry` | Spreadsheet Event Broadcaster |\n| `evolutionAppsUpdateEvent` | Account Updates |\n| `exemption` | Avalara |\n| `externalinvoices` | Mktplace Financial Commissions |\n| `fulfillment-points` | Admin Operational Capacity |\n| `giftCardList` | Gift Card List |\n| `import_session` | Products Import |\n| `import_session_config` | Products Import |\n| `instoreSettings` | Admin InStore (POS) |\n| `interaction` | Shipment Tracker |\n| `leyGondolas` | Admin Ley de Góndolas ARG |\n| `MASTERDATA_ENTITY (resolve name)` | WorldLine SIPS PPP |\n| `mcf_admin_app` | Amazon MCF Admin |\n| `module` | Sales Autopilot Service |\n| `multiTransaction` | Smiles Payment Provider MD |\n| `myWishlist` | Wishlist v2 |\n| `myWishlists` | myWishlists |\n| `notify` | Availability Notifier |\n| `onboarding` | Adyen Platforms |\n| `onboarding_modifications` | Orders GraphQL |\n| `ORDER_FISCAL_CODE` | Order SMS Notification |\n| `orderInfo` | Octopia (casino) |\n| `orders` | v2 Orders entity |\n| `ordersWithExternalPromotions` | External Promotion Monitoring GraphQL |\n| `organization_requests` | B2B Organizations GraphQL |\n| `organizations` | B2B Organizations GraphQL |\n| `paymentid2c2p` | Payment 2C2P |\n| `payuStatus` | PayU Europe Connector |\n| `pins` | Sales Performance GraphQL |\n| `productInfo` | Octopia (casino) |\n| `productReviews` | Reviews and Ratings |\n| `productsWithError` | Products Monitoring Service |\n| `promotionsCron` | Opt-in Campaign Service |\n| `promotionsTrack` | Opt-in Campaign Service |\n| `proposal` | Sales Autopilot Service |\n| `queuemessagevo` | v2 queue message value object |\n| `quotes` | B2B Quotes GraphQL |\n| `rangeSafelist` | Opt-in Campaign Listener |\n| `Reseller` | Easy Setup (legacy B2B seeder) |\n| `ReturnApp` | ReturnApp |\n| `returnRequest` | Return App |\n| `scheduler` | v2 scheduler |\n| `sellerInfo` | Vertex O Series |\n| `sellersdashboards` | Mktplace Financial Commissions |\n| `shipment` | Shipment Tracker |\n| `shopper` | v2 shopper profile |\n| `smilesProductMapping` | Smiles Payment Provider MD |\n| `smilesSellerConfiguration` | Smiles Payment Provider MD |\n| `smilesTransaction` | Smiles Payment Provider MD |\n| `smsMessagesSchema` | Orange SMS Integration |\n| `SNA` | Seller Notification App |\n| `statisticsdashboards` | Mktplace Financial Commissions |\n| `subscription` | v2 subscription (recurrent commerce) |\n| `taxFallback{provider}` | Tax Fallback |\n| `templates` | Marketing Autopilot Service |\n| `tradePolicyConfig` | Vertex O Series |\n| `trainingBanners` | Training Banners App |\n| `transaction` | Digital Currency |\n| `userAffiliation` | Affiliates |\n| `UserOrganization` | Easy Setup (legacy B2B seeder) |\n| `views` | Sales Performance GraphQL |\n| `vtex_admin_cms_graphql_content` | Admin CMS GraphQL (declares this v2 native) |\n| `vtex_admin_cms_graphql_contentVariant` | Admin CMS GraphQL (declares this v2 native) |\n| `wishlist` | Wishlist (legacy .NET) |\n| `wishlistitems` | Wishlist IO |\n| `wishlists` | Wishlist IO |\n\n## Custom data entities\n\nIn addition to the [native entities](#master-data-native-entities) automatically created by VTEX, such as `CL` (clients), `AD` (addresses), and other standard entities of the commerce platform, your operation can create custom data entities to store business-specific information.\n\nCustom entities can be created:\n\n- In v1, through the VTEX Admin. Learn how to [create a data entity](/docs/tutorials/data-entity).\n- In v2, exclusively through the [Master Data v2 API](https://developers.vtex.com/docs/api-reference/master-data-api-v2).\n\n### Billing\n\nThe use of native entities is free of charge. The use of custom entities is billed monthly, with tiers based on the total number of documents stored. For billing purposes, each file of up to 100KB is counted as one document.\n\nTo learn about the amount applicable to your operation, see your commercial agreement or contact [VTEX support](https://support.vtex.com/).\n\nFor each payment made during the term of the agreement, a billing credit corresponding to 2% of the net amount paid for VTEX Commerce Platform and CX Commerce Platform products will be granted. The credits accumulate throughout the term of the agreement and remain available for use until its termination.\n\nMeasurement and billing follow a monthly cycle:\n\n- At the end of each month, a snapshot of the document volume stored in non-native entities is generated.\n- By the 30th of each month, VTEX calculates the amounts related to Master Data usage and the applicable credits for the next invoice.\n\n\n> ℹ️ To view billing details, learn how to [download VTEX invoices](/docs/tutorials/how-to-download-the-vtex-invoices).\n\n## Applications\n\nBoth versions of Master Data are extremely flexible, allowing you to meet a variety of your store's needs. You may check below some examples of applying Master Data functionalities.\n\n### A/B Testing\n\nWith v2 triggers, you can establish multiple actions for the same trigger by setting the load percentage that each action should receive. Therefore, it is possible to comparatively test the impact of different automations on your store.\n\nLearn how to configure [A/B testing with Master Data v2](https://developers.vtex.com/vtex-rest-api/docs/setting-up-an-ab-test-with-master-data-v2-trigger).\n\n### Abandoned cart\n\nMaster Data can also be used to create abandoned cart integrations, i.e. performing automatic actions whenever clients add products to their store cart and log out without checking out.\n\nTo learn more, please see this guide on [abandoned cart configuration](/en/docs/tutorials/setting-up-abandoned-carts)"}