EDU-17995: add B2B Buyer Portal Master Data architecture guide

[PedroAntunesCosta]

Summary

Adds a new architecture guide for B2B Buyer Portal Master Data, mapping all seven Master Data entities, their fields, logical relationships, and integration patterns.

Changes

• Added b2b-buyer-portal-master-data-architecture.md under docs/guides/b2b/b2b-buyer-portal/

Why

Buyers and developers building integrations with B2B Buyer Portal need a clear map of how the underlying Master Data entities relate to each other. This guide provides that reference, with direct links to the API reference for each domain.

Related Task

EDU-17995

[github-actions]

👁️‍🗨️ Preview changes on Developer Portal

You can use the link below to load the Developer Portal in preview mode with the changes from this branch:

👉 Open preview environment

Below is the list of modified pages and their corresponding preview URLs:

File	Preview URL	Sidebar
docs/guides/b2b/b2b-buyer-portal/b2b-buyer-portal-master-data-architecture.md	https://developers.vtex.com/docs/guides/b2b-buyer-portal-master-data-architecture	⚠️ Missing from navigation.json

[github-actions]

🔍 Documentation feedback for docs/guides/b2b/b2b-buyer-portal/b2b-buyer-portal-master-data-architecture.md

Here is the review of the provided Explanation document based on the specified rules.

1. General Feedback

The document is well-structured, highly informative, and provides excellent context regarding the B2B Buyer Portal's Master Data architecture. It makes great use of tables and a Mermaid diagram to explain complex relationships (adhering to R1.4).

To fully align with the Explanation guidelines, some minor adjustments are needed:

• Cross-references (R1.5): The first occurrence of "B2B Buyer Portal" and "VTEX ID" should be hyperlinked to their respective official documentation.
• Instructional Tone (R1.2): The "Common integration patterns" section uses imperative verbs (e.g., Create, Assign, Persist), which can make the explanation read like a step-by-step guide. Rephrasing these to be descriptive ensures the text remains purely explanatory.

---

2. Actionable Feedback

• R1.5 (Cross-references):
  • Add a link to the first occurrence of B2B Buyer Portal in the very first paragraph of the introduction.
  • Add a link to VTEX ID on its first occurrence in the "Common integration patterns" section (e.g., linking to the VTEX ID overview or help documentation).
• R1.2 (Avoid step-by-step instructions):
  • In the Common integration patterns section, rephrase the bullet points to use descriptive, non-imperative language (e.g., change "Create or resolve a contract..." to "Involves creating or resolving a contract...").

---

3. Suggested Revision

---
title: "B2B Buyer Portal Master Data architecture"
slug: "b2b-buyer-portal-master-data-architecture"
hidden: false
createdAt: "2026-05-27T00:00:00.000Z"
updatedAt: "2026-05-28T00:00:00.000Z"
excerpt: "Map the Master Data entities and logical relationships that underpin B2B Buyer Portal integrations, and find the right integration guides and API references for each domain."
---

> ⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to selected accounts.

**[B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal)** persists buyer organization data across several [Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) entities. Understanding how those entities relate to each other is essential for building reliable integrations, particularly when orchestrating multi-step operations such as contract creation, address provisioning, or user onboarding.

This guide maps all seven Master Data entities used by B2B Buyer Portal, their fields, logical relationships, and common integration patterns. For the full operation set, parameters, and payload schemas, see the API reference linked in each section.

## Before you begin

- The store must have [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal) enabled.
- Familiarize yourself with [Master Data v1](https://developers.vtex.com/docs/api-reference/masterdata-api) and [Master Data v2](https://developers.vtex.com/docs/api-reference/master-data-api-v2) query syntax. Different entities use different versions, so query parameters, pagination conventions, and schema requirements vary.

## Entity overview

B2B Buyer Portal uses seven Master Data entities, each covering a distinct domain:

| Entity | Master Data name | Master Data version | Domain |
| :--- | :--- | :--- | :--- |
| Contract | `CL` | v1 | Root entity for a buyer organization's commercial conditions. |
| Address | `AD` | v1 | Shipping and billing destinations linked to a contract. |
| Buyer data | `shopper` | v1 | Enriched profile data for storefront users with purchase permission. |
| Custom field settings | `customFieldSettings` | v2 | Field definitions (type, level, requirements) per contract. |
| Custom field values | `customFieldValues` | v2 | Values filled in for custom fields, optionally tied to an address. |
| Recipients | `contact_information` | v2 | People authorized to receive shipments at a given address. |
| Default values | `defaultValues` | v1 | Pre-configured checkout defaults per organizational unit. |

## Entity relationships

The diagram shows logical references between entities. Edge labels are the field names used as foreign keys in the child record. 

[`OrgUnit`](https://developers.vtex.com/docs/guides/b2b-buyer-portal-integration-overview#organizational-units-and-scopes) and storefront [`User`](https://developers.vtex.com/docs/guides/b2b-buyer-portal-integration-overview#user-provisioning) records are not Master Data entities. They appear here because several Master Data entities reference organizational unit IDs or VTEX user IDs.

```mermaid
flowchart TB
    CL --> OrgUnit
    CL -->|"userId"| AD
    CL -->|"contractId"| customFieldSettings
    CL -->|"contractId"| customFieldValues
    CL -->|"profileId"| contact_information
    AD -->|"addressIds"| contact_information
    AD -->|"auxId"| customFieldValues
    customFieldSettings -->|"customFieldId"| customFieldValues
    OrgUnit -->|"id"| defaultValues
    AD -->|"entityValueId"| defaultValues
    customFieldValues -->|"entityValueId"| defaultValues
    OrgUnit -->|"userId"| User
    User -->|"userId"| shopper
```

> ℹ️ All relationships are logical references managed at the application layer. Master Data does not enforce referential integrity, so deleting a parent document does not cascade to its children.

## Key linking fields

Use this table when orchestrating multi-step flows. It lists only the fields that connect entities. For every other attribute, see the API reference for that entity.

| Child entity | Linking field | Points to | Parent / target |
| :--- | :--- | :--- | :--- |
| `AD` (address) | `userId` | `CL.id` | Contract that owns the address |
| `customFieldSettings` | `contractId` | `CL.id` | Contract the field belongs to |
| `customFieldValues` | `contractId` | `CL.id` | Contract the value belongs to |
| `customFieldValues` | `auxId` | `AD.id` | Address, when the value is a location |
| `customFieldValues` | `customFieldId` | `customFieldSettings.id` | Field definition, required for locations |
| `contact_information` (recipient) | `profileId` | `CL.id` | Contract that owns the recipient |
| `contact_information` (recipient) | `addressIds` | `AD.id` (array) | Addresses the recipient can receive at |
| `defaultValues` | `id` | Org unit ID | Organizational unit (set explicitly, not auto-generated) |
| `defaultValues` | `entityValueId` | `AD.id` or `customFieldValues.id` | Default shipping/billing address or custom field value |
| `shopper` (buyer data) | `userId` | VTEX user ID | Storefront user from VTEX ID, not the contract |

## Common integration patterns

- **Contract-first provisioning:** Involves creating or resolving a contract (`CL`) before addresses, custom fields, or recipients. Child records reference `CL.id` through `userId`, `contractId`, or `profileId`.
- **Address and destination setup:** Consists of creating addresses (`AD`), then optionally attaching recipients (`contact_information`) and locations (`customFieldValues` through `auxId` and a location-type custom field setting).
- **User onboarding:** Requires creating the storefront user in [VTEX ID](https://help.vtex.com/en/tutorial/vtex-id--68697858345), assigning [organizational units and roles](https://developers.vtex.com/docs/guides/b2b-user-provisioning), and then persisting buyer data in `shopper` linked by `userId`.

## Entities by domain

The subsections below describe each entity's role in the model and where to find implementation details. Field-level attributes are documented in the API reference for each entity.

### Contract (`CL`)

The contract is the **root** of every buyer organization. Its `id` anchors addresses, custom fields, and recipients. Commercial conditions such as assortment, pricing, and payment restrictions live on this record.

- **Integration guide:** [Contracts (B2B Buyer Portal integration overview)](https://developers.vtex.com/docs/guides/b2b-buyer-portal-integration-overview#contracts)
- **API reference:** [B2B Contracts API](https://developers.vtex.com/docs/api-reference/b2b-contracts-api)

### Addresses, recipients, and locations

Three entities work together for checkout destinations:

| Concept | Data entity | Role in the model |
| :--- | :--- | :--- |
| Address | `AD` | Shipping (`commercial`) or billing (`invoice`) destination. `AD.id` is reused when linking recipients and locations. |
| Recipient | `contact_information` | Person selectable as order recipient. Scoped to a contract via `profileId`, optionally narrowed to specific addresses via `addressIds`. |
| Location | `customFieldValues` | Delivery point within an address (dock, department, area). Linked through `auxId` and a location-type custom field setting. |

- **Integration guide:** [B2B Addresses integration](https://developers.vtex.com/docs/guides/b2b-addresses-integration)
- **API reference:** [B2B Addresses API](https://developers.vtex.com/docs/api-reference/b2b-addresses)

### Custom field settings and values

Custom fields (accounting fields) are split across two entities:

| Concept | Data entity | Role in the model |
| :--- | :--- | :--- |
| Settings | `customFieldSettings` | Defines field name, type, level (`order`, `item`, `address`), and requirements per contract. |
| Values | `customFieldValues` | Stores predefined options or location records. Location values reference both a contract and an address (`auxId`). |

- **Integration guide:** [Custom Fields integration](https://developers.vtex.com/docs/guides/custom-fields-integration)
- **API reference:** [Custom Fields API](https://developers.vtex.com/docs/api-reference/custom-fields-api)

> ℹ️ Search and get operations on v2 entities (`customFieldSettings`, `customFieldValues`, `contact_information`) require `_schema=v1` in the query string. See the integration guides above for filter patterns.

### Buyer data (`shopper`)

The `shopper` entity stores enriched profile attributes for a **storefront user**. It links to VTEX ID through `userId`, not to a contract. User provisioning creates the VTEX user first, then persists buyer data.

- **Integration guide:** [B2B user provisioning](https://developers.vtex.com/docs/guides/b2b-user-provisioning)
- **API reference:** [B2B Buyer Data API](https://developers.vtex.com/docs/api-reference/b2b-buyer-data-api)

### Default values (`defaultValues`)

Default values pre-fill checkout for an organizational unit. The document `id` equals the org unit ID. Each entry in the `defaultValues` array maps an `entity` path (for example, `address/shipping`, `customFieldValues/{fieldName}`) to an `entityValueId` pointing at an address or custom field value record.

- **Integration guide:** [Default Values integration](https://developers.vtex.com/docs/guides/default-values-integration)
- **API reference:** [Default Values API](https://developers.vtex.com/docs/api-reference/default-values-api) and [Master Data API v1](https://developers.vtex.com/docs/api-reference/masterdata-api) (`defaultValues` data entity)

## Next steps

- [B2B Buyer Portal integration overview](https://developers.vtex.com/docs/guides/b2b-buyer-portal-integration-overview): Capability map across contracts, organization management, addresses, accounting fields, and more.
- [B2B Addresses integration](https://developers.vtex.com/docs/guides/b2b-addresses-integration): Addresses, recipients, and locations.
- [Custom Fields integration](https://developers.vtex.com/docs/guides/custom-fields-integration): Custom checkout field settings and values.
- [Default Values integration](https://developers.vtex.com/docs/guides/default-values-integration): Checkout defaults per organizational unit.
- [B2B user provisioning](https://developers.vtex.com/docs/guides/b2b-user-provisioning): Storefront users, org units, roles, and buyer data.

---

Was this feedback useful?

• Yes
• No

Review made on commit 53e6713