{"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 highly customizable VTEX platform solution for databases, which also allows you to create applications.\n\nBy default, Master Data is used to store and organize your store's customer data. It features a powerful search engine that allows you to store, search, expand, and customize data.\n\nIn this article, you'll find details about each available version of Master Data, key concepts, and how to use them.\n\n> ℹ️ Note that depending on the feature and version you want to use, you'll need to contact your operation's development team.\n\n## Available versions\n\nThere are currently two available versions, and you can choose the one that best fits your operation's needs. The main difference between the two is that v2 doesn't have a graphical interface and can only be used through the [Master Data API v2](https://developers.vtex.com/docs/api-reference/master-data-api-v2), even though it has other relevant features, 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 your store's customer data in Master Data v1.\n\nCheck the table below to learn more about how the features of each version differ.\n\n| Functionality | v1 | v2 | Learn more |\n| :--- | :--- | :--- | :--- |\n| Graphical interface | ✅ Yes | ❌ No | - |\n| API | ✅ Yes | ✅ Yes | - [Master Data API v1](https://developers.vtex.com/docs/api-reference/masterdata-api)
- [Master Data API v2](https://developers.vtex.com/docs/api-reference/master-data-api-v2#overview) |\n| Spreadsheet import and export | ✅ Yes | ❌ No | - [Importing data to Master Data v1](/docs/tutorials/importing-data-into-master-data-v1)
- [Exporting data from Master Data v1](/docs/tutorials/exporting-data) |\n| Attachments (images) | ✅ Yes | ❌ No | - |\n| Triggers | ✅ Yes | ✅ Yes | - [Triggers](#triggers)
- [Creating triggers with Master Data v1](/docs/tutorials/creating-trigger-in-master-data)
- [Creating triggers with Master Data v2](https://developers.vtex.com/docs/guides/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)
- [Getting started with JSON schemas in Master Data v2](https://developers.vtex.com/docs/guides/starting-to-work-on-master-data-with-json-schema)
- [Schema lifecycle in Master Data v2](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) |\n| Nested properties | ❌ No | ✅ Yes | - [Nested properties](#nested-properties) |\n| Data entities | Referenced by acronyms composed of two uppercase letters. For example, the entity 'CL' stores customer data, and 'AD' stores their address data. They can't be created via API. | Referenced by name. For example, 'Notification'. They can only be created via API. | - [Data entities](#data-entities)
- [Data entities in Master Data v1](/docs/tutorials/data-entity)
- [Creating relationships between Master Data v2 data entities](https://developers.vtex.com/docs/guides/creating-relationships-between-data-entities-using-api) |\n| Fields | They must be completed in the specific format configured in the data entity. | In principle, there are no restrictions on fields or formats. Format validation happens through JSON schemas. | - [Field types in Master Data v1](/docs/tutorials/data-entity#data-types)
- [JSON schemas](#v2-schemas) |\n| Indexes | ✅ Yes | ✅ Yes | - [Configure indices in Master Data v1](/docs/tutorials/indexes-in-master-data)
- [Configure indices with the 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 data created in a v1 entity can't be queried or edited using v2 resources and vice versa.\n\n## Basic components\n\nBoth versions of Master Data use some basic components equivalent to concepts found in other database solutions, under different names such as records or tables. Below, you'll 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 like tables where documents and fields are recorded.\n\nMaster Data v1 data entities are referenced by acronyms composed of two uppercase letters. In v2, you can use the data entity name instead. For example, in v1 the `CL` entity stores customer data, while `AD` stores their address data. Equivalent entities in v2 can be referenced with names such as `Client` and `Address`.\n\nIn a data entity, information is structured into [documents](#documents) and [fields](#fields).\n\n### Documents\n\nDocuments are records within a data entity. If data entities are like tables, each document is a row in a table.\n\nFor example, within a data entity that stores the store's customer data, such as `CL` or `Client`, each document contains information about a customer.\n\nEach document has an ID automatically generated by the platform when it's created, a unique code that identifies that record.\n\n### Fields\n\nThe attributes that compose Master Data documents are called fields. When comparing data entities to tables, you can think of fields as the columns of a table.\n\nFor example, in an entity that stores the store's customer data, such as `CL` or `Client`, you can complete fields like **name**, **email**, **date of birth**, and **document**.\n\nIn Master Data v1, fields must be completed in the specific format configured for the data entity. Learn more about [field types in Master Data v1](/docs/tutorials/data-entity).\n\nIn v2, however, there's no restriction on fields or formats at first. Format validation happens through [JSON schemas](#v2-schemas).\n\n#### Nested properties\n\nMaster Data v2 allows you to structure data with nested properties, a format often used in [JSON](https://www.json.org/json-en.html). This concept allows you to create fields composed of other fields for better data structuring. For example, a customer profile can have a `Document` field, which in turn is composed of the `Type` and `Number` properties. You can also create nested [triggers](#triggers).\n\n### Indexes\n\nIndexes are used to specify a document to be accessed, identified by an indexed field instead of its ID.\n\nAs mentioned above, each document has an ID automatically generated by the platform when it's created. If you want to query a document but don't know its ID, you can use indexes.\n\nFor example, you can query a document containing a customer's information by specifying the value of the `email` field associated with that customer.\n\n> ℹ️ Learn more about how to [configure indexes in Master Data v1](/docs/tutorials/indexes-in-master-data) or [configure indexes with the 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 executes an action after a document is created or updated, provided the conditions set in the configuration are met. These actions can be of three types:\n\n- Submit HTTP request.\n- Send email.\n- Save a document in another data entity.\n\nLearn more about how to [configure triggers in Master Data v1](/docs/tutorials/creating-trigger-in-master-data) or how to [configure triggers with the 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 using JSON schemas. This format indicates how Master Data should validate and index documents.\n\n> ℹ️ Learn more about [JSON schemas](https://json-schema.org/).\n\nYou can save a document in any data entity as long as the content is 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, or with none at all.\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| `ad` | Customer addresses |\n| `AS` | Availability Notifier (most likely source) |\n| `au` | Audit log |\n| `bb` | Buzz billing |\n| `bk` | Bucket (generic key/value) |\n| `bo` | BridgeOrder |\n| `bx` | Buzz extract |\n| `cl` | Customer accounts (clients) |\n| `CS` | Casino Gift Card |\n| `gc` | Gift cards |\n| `gt` | Gift card constraints |\n| `hl` | Holidays |\n| `il` | Internal logs |\n| `iw` | Internal warnings |\n| `iy` | Availability item |\n| `mb` | BridgeOrderMarketplace |\n| `od` | Orders |\n| `rd` | Order (mirror) |\n| `sb` | BridgeOrderSeller |\n| `se` | - |\n| `sl` | - |\n| `so` | Stores |\n| `SP` | Smiles Checkout Middleware |\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| `agentchangeappstate` | Agent change app state |\n| `aggregateddayorders` | Aggregated day orders |\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| `commissioningreportentry` | Commissioning report entry |\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| `dataentitysettings` | Data entity settings |\n| `defaultValues` | defaultValues |\n| `eventinfo` | Worldline Global Collect |\n| `eventRegistry` | Spreadsheet Event Broadcaster |\n| `evolutionAppsUpdateEvent` | Account Updates |\n| `evolutiondeloreanupdateevent` | Evolution Delorean update event |\n| `evolutionworkspacepromotion` | Evolution workspace promotion |\n| `exemption` | Avalara |\n| `externalinvoices` | Mktplace Financial Commissions |\n| `fbeconfiguration` | FBE configuration |\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| `logisticsorderinfo` | Logistics order info |\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| `packages` | Packages |\n| `paymentid2c2p` | Payment 2C2P |\n| `payuStatus` | PayU Europe Connector |\n| `pickup_points` | Pickup points |\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| `report_generations` | Report generations |\n| `report_maps` | Report maps |\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| `srapi` | SRAPI |\n| `statisticsdashboards` | Mktplace Financial Commissions |\n| `stores` | Stores |\n| `subscription` | v2 subscription (recurrent commerce) |\n| `subscription_cohort` | Subscription cohort |\n| `subscription_history` | Subscription history |\n| `subscription_orders` | Subscription orders |\n| `subscriptions` | Subscriptions |\n| `subscriptions_group` | Subscriptions group |\n| `subscriptions_thin` | Subscriptions thin |\n| `templates` | Marketing Autopilot Service |\n| `tms_orders` | TMS orders |\n| `tradePolicyConfig` | Vertex O Series |\n| `trainingBanners` | Training Banners App |\n| `transactions` | Digital Currency |\n| `transportation_order` | Transportation order |\n| `userAffiliation` | Affiliates |\n| `UserOrganization` | Easy Setup (legacy B2B seeder) |\n| `vendors` | Vendors |\n| `vendors_carts` | Vendors carts |\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| `vtex_orders_graphql_onboardingusers` | Orders GraphQL onboarding users |\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` (customers), `AD` (addresses), and other default entities of the commerce platform, your operation can create custom data entities to store business-specific information.\n\nYou can create custom entities as follows:\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 up to 100KB is counted as one document.\n\nTo learn about the amounts applicable to your operation, see your commercial agreement or contact [VTEX support](https://help.vtex.com/en/support).\n\nFor each payment made during the term of the agreement, a billing credit equivalent to 2% of the net amount paid for VTEX Commerce Platform and CX Commerce Platform products is granted. The credits accumulate throughout 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 number of documents stored in custom 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> ℹ️ To track the number of documents in custom entities throughout the month, check the **Master Data usage** dashboard in the VTEX Admin. This dashboard is updated weekly and is intended only for usage tracking. To learn how to access it, see [Checking Master Data usage in the VTEX Admin](/docs/tutorials/checking-master-data-usage-in-the-vtex-admin).\n\n> ℹ️ To view billing details, learn how to [download VTEX invoices](/docs/tutorials/how-to-download-the-vtex-invoices).\n\n## Use cases\n\nBoth versions of Master Data are natively suitable for managing your store's customer data. As mentioned above, they're extremely flexible, allowing you to meet a variety of your store's needs. See below some examples of how Master Data features can be applied beyond basic customer data management.\n\n### A/B tests\n\nWith v2 triggers, you can configure multiple actions for the same trigger and define the percentage of load each action should receive. This allows you to comparatively test the impact of different automations in your store.\n\nLearn how to configure [A/B tests 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. In other words, automatic actions triggered whenever a customer adds products to the cart and ends their session without completing the purchase.\n\nTo learn more, see this guide on [configuring abandoned cart](/docs/tutorials/setting-up-abandoned-carts)"}