From b6997618e51258424e2daf3a3a68643ecc3dd050 Mon Sep 17 00:00:00 2001 From: Shantanu Dasgupta Date: Mon, 6 Jul 2026 13:41:40 +0530 Subject: [PATCH 01/10] Added new pages for Company address book mutations --- .../b2b/company/mutations/create-address.md | 255 ++++++++++++++++++ .../b2b/company/mutations/delete-address.md | 54 ++++ .../schema/b2b/company/mutations/index.md | 7 + .../company/mutations/set-default-address.md | 95 +++++++ .../b2b/company/mutations/update-address.md | 102 +++++++ .../schema/b2b/company/queries/company.md | 128 +++++++++ 6 files changed, 641 insertions(+) create mode 100644 src/pages/graphql/schema/b2b/company/mutations/create-address.md create mode 100644 src/pages/graphql/schema/b2b/company/mutations/delete-address.md create mode 100644 src/pages/graphql/schema/b2b/company/mutations/set-default-address.md create mode 100644 src/pages/graphql/schema/b2b/company/mutations/update-address.md diff --git a/src/pages/graphql/schema/b2b/company/mutations/create-address.md b/src/pages/graphql/schema/b2b/company/mutations/create-address.md new file mode 100644 index 000000000..7e3f9e91e --- /dev/null +++ b/src/pages/graphql/schema/b2b/company/mutations/create-address.md @@ -0,0 +1,255 @@ +--- +title: createCompanyAddress mutation +description: The createCompanyAddress mutation allows a company admin or user who is assigned a role that contains the Magento_CompanyAddressStorefrontCompatibility::add permission to create a new company address. +keywords: + - B2B +--- + + + +# createCompanyAddress mutation + + + +This mutation is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + +The `createCompanyAddress` mutation allows a company admin or user who is assigned a role that contains the `Magento_CompanyAddressStorefrontCompatibility::add` permission to create a new company address. + +This mutation requires a valid [customer authentication token](../../../customer/mutations/generate-token.md). + +## Syntax + +```graphql +mutation { + createCompanyAddress( + input: CompanyAddressInput! + ) { + CompanyAddress + } +} +``` + +## Example usage + +### Create a company address (type: billing) + +The following example creates a company billing address. + +**Request:** + +```graphql +mutation CreateCompanyAddress { + createCompanyAddress( + input: { + nickname: "HQ Billing" + address_type: BILLING + is_default: true + firstname: "John" + lastname: "Doe" + middlename: "Q" + prefix: "Mr." + suffix: "Jr." + company: "Company name" + street: ["123 Main St"] + city: "Austin" + country_code: US + region: { + region_id: 57 + region: "Texas" + region_code: "TX" + } + postcode: "78701" + telephone: "5551234567" + fax: "5551234568" + vat_id: "US123456789" + custom_attributes: [ + { attribute_code: "my_custom_attr", value: "custom value" } + ] + } + ) { + id + nickname + company_id + address_type + is_default + firstname + lastname + middlename + prefix + suffix + company + street + city + country_code + region_id + region { + region_id + region + region_code + } + postcode + telephone + fax + vat_id + custom_attributes { + code + ... on AttributeValue { + value + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "createCompanyAddress": { + "id": "MTI=", + "nickname": "HQ Billing", + "company_id": "Mw==", + "address_type": "BILLING", + "is_default": true, + "firstname": "John", + "lastname": "Doe", + "middlename": "Q", + "prefix": "Mr.", + "suffix": "Jr.", + "company": "Company name", + "street": ["123 Main St"], + "city": "Austin", + "country_code": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78701", + "telephone": "5551234567", + "fax": "5551234568", + "vat_id": "US123456789", + "custom_attributes": [] + } + } +} +``` + +### Create a company address (type: shipping) + +The following example creates a company billing address. + +**Request:** + +```graphql +mutation CreateCompanyAddress { + createCompanyAddress( + input: { + nickname: "HQ Shipping" + address_type: SHIPPING + is_default: true + firstname: "John" + lastname: "Doe" + middlename: "Q" + prefix: "Mr." + suffix: "Jr." + company: "Company name" + street: ["123 Main St"] + city: "Austin" + country_code: US + region: { + region_id: 57 + region: "Texas" + region_code: "TX" + } + postcode: "78701" + telephone: "5551234567" + fax: "5551234568" + vat_id: "US123456789" + custom_attributes: [ + { attribute_code: "my_custom_attr", value: "custom value" } + ] + } + ) { + id + nickname + company_id + address_type + is_default + firstname + lastname + middlename + prefix + suffix + company + street + city + country_code + region_id + region { + region_id + region + region_code + } + postcode + telephone + fax + vat_id + custom_attributes { + code + ... on AttributeValue { + value + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "createCompanyAddress": { + "id": "MTM=", + "nickname": "HQ Shipping", + "company_id": "Mw==", + "address_type": "SHIPPING", + "is_default": true, + "firstname": "John", + "lastname": "Doe", + "middlename": "Q", + "prefix": "Mr.", + "suffix": "Jr.", + "company": "Company name", + "street": ["123 Main St"], + "city": "Austin", + "country_code": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78701", + "telephone": "5551234567", + "fax": "5551234568", + "vat_id": "US123456789", + "custom_attributes": [] + } + } +} +``` + +## Errors + +| Error | Description | +| --- | --- | +| `Customer is not a company user.` | Not authenticated or not a company user | +| `Company context is required.` | Missing `X-Adobe-Company` header | +| `Company address book is not enabled for this company.` | Address book disabled for company | +| `You do not have authorization to perform this action.` | Missing add or set-default ACL | + + diff --git a/src/pages/graphql/schema/b2b/company/mutations/delete-address.md b/src/pages/graphql/schema/b2b/company/mutations/delete-address.md new file mode 100644 index 000000000..d2c9f50b6 --- /dev/null +++ b/src/pages/graphql/schema/b2b/company/mutations/delete-address.md @@ -0,0 +1,54 @@ +--- +title: deleteCompanyAddress mutation +description: The deleteCompanyAddress mutation allows a company admin or user who is assigned a role that contains the Magento_CompanyAddressStorefrontCompatibility::delete permission to delete an existing company address. +keywords: + - B2B +--- + + + +# deleteCompanyAddress mutation + + + +This mutation is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + +The `deleteCompanyAddress` mutation allows a company admin or user who is assigned a role that contains the `Magento_CompanyAddressStorefrontCompatibility::delete` permission to delete an existing company address using a provided company UID. + +This mutation requires a valid [customer authentication token](../../../customer/mutations/generate-token.md). + +## Syntax + +```graphql +mutation { + deleteCompanyAddress( + id: ID! + ) { + Boolean + } +} +``` + +## Example usage + +### Delete a company address + +The following example deletes an existing company address. + +**Request:** + +```graphql +mutation DeleteCompanyAddress { + deleteCompanyAddress(id: "MTI=") +} +``` + +**Response:** + +```json +{ + "data": { + "deleteCompanyAddress": true + } +} +``` diff --git a/src/pages/graphql/schema/b2b/company/mutations/index.md b/src/pages/graphql/schema/b2b/company/mutations/index.md index dfa398391..4a2adca8a 100644 --- a/src/pages/graphql/schema/b2b/company/mutations/index.md +++ b/src/pages/graphql/schema/b2b/company/mutations/index.md @@ -17,3 +17,10 @@ The B2B company mutations allow you to perform the management operations: * Move the position of a company team in the company hierarchy. * Create, update, and delete company roles. * Assign and unassign a company to a company hierarchy. + +# Company Address Book mutations + +The company address book mutations allow you to perform the company address management operations: + +* Create, update and delete a company address. +* Set default company billing or shipping address. \ No newline at end of file diff --git a/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md b/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md new file mode 100644 index 000000000..885451d35 --- /dev/null +++ b/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md @@ -0,0 +1,95 @@ +--- +title: setDefaultCompanyAddress mutation +description: The setDefaultCompanyAddress mutation allows a company admin or user who is assigned a role that contains the Magento_CompanyAddressStorefrontCompatibility::default permission to set a company address based on the provided address UID as the default billing or shipping address for the company. +keywords: + - B2B +--- + + + +# setDefaultCompanyAddress mutation + + + +This mutation is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + +The `setDefaultCompanyAddress` mutation allows a company admin or user who is assigned a role that contains the `Magento_CompanyAddressStorefrontCompatibility::default` permission to set a company address based on the provided address UID as the default billing or shipping address for the company. + +This mutation requires a valid [customer authentication token](../../../customer/mutations/generate-token.md). + +## Syntax + +```graphql +mutation { + setDefaultCompanyAddress( + id: ID! + ) { + CompanyAddress + } +} +``` + +## Example usage + +### Set a company address as default (BILLING/SHIPPING) + +The following example sets an existing company address as default. + +**Request:** + +```graphql +mutation SetDefaultCompanyAddress { + setDefaultCompanyAddress(id: "MTI=") { + id + address_type + is_default + nickname + city + country_code + } +} +``` + +**Response (Billing):** + +```json +{ + "data": { + "setDefaultCompanyAddress": { + "id": "MTI=", + "address_type": "BILLING", + "is_default": true, + "nickname": "HQ Billing", + "city": "Austin", + "country_code": "US" + } + } +} +``` +**Response (Shipping):** + +```json +{ + "data": { + "setDefaultCompanyAddress": { + "id": "MTM=", + "address_type": "SHIPPING", + "is_default": true, + "nickname": "Warehouse", + "city": "Austin", + "country_code": "US" + } + } +} +``` + +After setting defaults, you can read them from the Company type: + +```graphql +{ + company { + default_billing_address { id address_type is_default } + default_shipping_address { id address_type is_default } + } +} +``` \ No newline at end of file diff --git a/src/pages/graphql/schema/b2b/company/mutations/update-address.md b/src/pages/graphql/schema/b2b/company/mutations/update-address.md new file mode 100644 index 000000000..c0cb27865 --- /dev/null +++ b/src/pages/graphql/schema/b2b/company/mutations/update-address.md @@ -0,0 +1,102 @@ +--- +title: updateCompanyAddress mutation +description: The updateCompanyAddress mutation allows a company admin or user who is assigned a role that contains the Magento_CompanyAddressStorefrontCompatibility::edit permission to update an existing company address. +keywords: + - B2B +--- + + + +# updateCompanyAddress mutation + + + +This mutation is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + +The `updateCompanyAddress` mutation allows a company admin or user who is assigned a role that contains the `Magento_CompanyAddressStorefrontCompatibility::edit` permission to update an existing company address. + +This mutation requires a valid [customer authentication token](../../../customer/mutations/generate-token.md). + +## Syntax + +```graphql +mutation { + updateCompanyAddress( + id: ID! + input: CompanyAddressInput! + ) { + CompanyAddress + } +} +``` + +## Example usage + +### Update a company address + +The following example updates an existing company address. + +**Request:** + +```graphql +mutation UpdateCompanyAddress { + updateCompanyAddress( + id: "MTI=" + input: { + nickname: "Updated Nickname" + address_type: BILLING + is_default: false + firstname: "Jane" + lastname: "Smith" + company: "Updated Corp" + street: ["456 Oak Ave"] + city: "Dallas" + country_code: US + region: { + region_id: 57 + region: "Texas" + region_code: "TX" + } + postcode: "75201" + telephone: "5559876543" + } + ) { + id + nickname + address_type + is_default + firstname + lastname + company + city + street + country_code + postcode + telephone + } +} +``` + +**Response:** + +```json +{ + "data": { + "updateCompanyAddress": { + "id": "MTI=", + "nickname": "Updated Nickname", + "address_type": "BILLING", + "is_default": false, + "firstname": "Jane", + "lastname": "Smith", + "company": "Updated Corp", + "city": "Dallas", + "street": ["456 Oak Ave"], + "country_code": "US", + "postcode": "75201", + "telephone": "5559876543" + } + } +} +``` +Clearing default via `is_default`: false on an address that is currently default requires set-default ACL (same as setDefaultCompanyAddress). \ No newline at end of file diff --git a/src/pages/graphql/schema/b2b/company/queries/company.md b/src/pages/graphql/schema/b2b/company/queries/company.md index 9b6869b1a..cb0c94ca6 100644 --- a/src/pages/graphql/schema/b2b/company/queries/company.md +++ b/src/pages/graphql/schema/b2b/company/queries/company.md @@ -384,3 +384,131 @@ query{ } } ``` + +### Return the company addresses and config + +The following query returns a list of company's addresses and a config object related to addresses. + +**Request:** + +```graphql +query{ + company{ + id + config { + address_book_enabled + address_book_custom_shipping_address_enabled + } + addresses(pageSize: 20, currentPage: 1) { + total_count + page_info { + page_size + current_page + total_pages + } + items { + id + nickname + company_id + address_type + is_default + firstname + lastname + company + street + city + country_code + region_id + region { + region_id + region + region_code + } + postcode + telephone + fax + vat_id + custom_attributes { + code + ... on AttributeValue { + value + } + } + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "company": { + "config": { + "address_book_enabled": true, + "address_book_custom_shipping_address_enabled": true + }, + "addresses": { + "total_count": 2, + "page_info": { + "page_size": 20, + "current_page": 1, + "total_pages": 1 + }, + "items": [ + { + "id": "MTI=", + "nickname": "HQ Billing", + "company_id": "Mw==", + "address_type": "BILLING", + "is_default": true, + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": ["123 Main St"], + "city": "Austin", + "country_code": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78701", + "telephone": "5551234567", + "fax": null, + "vat_id": "US123456789", + "custom_attributes": [] + }, + { + "id": "MTM=", + "nickname": "Warehouse", + "company_id": "Mw==", + "address_type": "SHIPPING", + "is_default": false, + "firstname": "Jane", + "lastname": "Smith", + "company": "Acme Corp", + "street": ["456 Oak Ave"], + "city": "Dallas", + "country_code": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "75201", + "telephone": "5559876543", + "fax": null, + "vat_id": null, + "custom_attributes": [] + } + ] + } + } + } +} +``` \ No newline at end of file From 68fe4b3504e72bed871bc6e8ba492b2819f2825a Mon Sep 17 00:00:00 2001 From: Deepak Date: Fri, 24 Jul 2026 21:06:38 +0530 Subject: [PATCH 02/10] CAB Phase 2 related example added --- .../cart/mutations/set-billing-address.md | 155 +++++++++++++++++ .../cart/mutations/set-shipping-address.md | 163 ++++++++++++++++++ 2 files changed, 318 insertions(+) diff --git a/src/pages/graphql/schema/cart/mutations/set-billing-address.md b/src/pages/graphql/schema/cart/mutations/set-billing-address.md index 101595ae4..3deb5e6a5 100644 --- a/src/pages/graphql/schema/cart/mutations/set-billing-address.md +++ b/src/pages/graphql/schema/cart/mutations/set-billing-address.md @@ -21,6 +21,8 @@ The `setBillingAddressOnCart` reference provides detailed information about the ## Example usage +### Create a new billing address + The following example creates a new billing address for a specific cart. **Request:** @@ -115,6 +117,158 @@ mutation { } ``` +### Assign an existing customer address + +The following example assigns a billing address from the customer's address book by specifying the `customer_address_uid` value. This value is a UID-encoded reference to the address, not the raw `id` value. This field requires a valid [customer authentication token](../../customer/mutations/generate-token.md); guests cannot use `customer_address_uid`. + +**Request:** + +```graphql +mutation { + setBillingAddressOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + billing_address: { + customer_address_uid: "MQ==" + } + } + ) { + cart { + billing_address { + firstname + lastname + street + city + region { + code + label + } + postcode + telephone + country { + code + label + } + uid + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "setBillingAddressOnCart": { + "cart": { + "billing_address": { + "firstname": "Jane", + "lastname": "Doe", + "street": [ + "123 Main Street" + ], + "city": "Austin", + "region": { + "code": "TX", + "label": "Texas" + }, + "postcode": "78758", + "telephone": "5551234567", + "country": { + "code": "US", + "label": "US" + }, + "uid": "MQ==" + } + } + } + } +} +``` + +### Assign a company address (B2B) + + + +[SaaS only](https://experienceleague.adobe.com/en/docs/commerce/user-guides/product-solutions) + + + +The `company_address_id` field is part of the B2B Storefront Compatibility Package and is available with [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview), and with [Adobe Commerce Optimizer](https://experienceleague.adobe.com/en/docs/commerce/aco-optimizer-connector/overview) on Adobe Commerce on cloud infrastructure or on-premises. The field references the **company** address book, not the customer's personal address book, and is available only to an authenticated B2B company user whose company has the company address book feature enabled (`is_company_address_book_enabled`); guests cannot use this field. `company_address_id` is a GraphQL-only field with no REST equivalent. Like `customer_address_uid`, the value is a UID-encoded reference, not a raw integer. + +The following example assigns a billing address from the company's address book by specifying the `company_address_id` value returned by the [`createCompanyAddress`](../../b2b/company/mutations/create-address.md) mutation. + +**Request:** + +```graphql +mutation { + setBillingAddressOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + billing_address: { + company_address_id: "MjAy" + } + } + ) { + cart { + billing_address { + firstname + lastname + company + street + city + region { + code + label + } + postcode + telephone + country { + code + label + } + company_address_id + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "setBillingAddressOnCart": { + "cart": { + "billing_address": { + "firstname": "John", + "lastname": "Doe", + "company": "Company name", + "street": [ + "123 Main St" + ], + "city": "Austin", + "region": { + "code": "TX", + "label": "Texas" + }, + "postcode": "78701", + "telephone": "5551234567", + "country": { + "code": "US", + "label": "US" + }, + "company_address_id": "MjAy" + } + } + } + } +} +``` + ## Errors | Error | Description | @@ -129,3 +283,4 @@ mutation { | `Could not use the "use_for_shipping" option, because multiple shipping addresses have already been set.` | The `use_for_shipping` flag was provided, but the cart already has multiple shipping addresses. | | `The current customer isn't authorized.` | An unauthorized user (guest) tried to set a billing address on behalf of an authorized user (customer), or a customer tried to set a billing address on behalf of another customer. | | `An error occurred while processing the billing address.` | The billing address could not be validated. One or more required fields may be missing or invalid. | +| `Company address book is not enabled for this company.` | The `company_address_id` field was specified, but the customer's company does not have `is_company_address_book_enabled` set. | diff --git a/src/pages/graphql/schema/cart/mutations/set-shipping-address.md b/src/pages/graphql/schema/cart/mutations/set-shipping-address.md index c03c40241..5ee4026b9 100644 --- a/src/pages/graphql/schema/cart/mutations/set-shipping-address.md +++ b/src/pages/graphql/schema/cart/mutations/set-shipping-address.md @@ -24,6 +24,8 @@ The `setShippingAddressesOnCart` reference provides detailed information about t ## Example usage +### Create a new shipping address + **Request:** ```graphql @@ -122,6 +124,166 @@ mutation { } ``` +### Assign an existing customer address + +The following example assigns a shipping address from the customer's address book by specifying the `customer_address_uid` value. This value is a UID-encoded reference to the address, not the raw `id` value. This field requires a valid [customer authentication token](../../customer/mutations/generate-token.md); guests cannot use `customer_address_uid`. + +**Request:** + +```graphql +mutation { + setShippingAddressesOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + shipping_addresses: [ + { + customer_address_uid: "MQ==" + } + ] + } + ) { + cart { + shipping_addresses { + firstname + lastname + street + city + region { + code + label + } + postcode + telephone + country { + code + label + } + uid + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "setShippingAddressesOnCart": { + "cart": { + "shipping_addresses": [ + { + "firstname": "Jane", + "lastname": "Doe", + "street": [ + "123 Main Street" + ], + "city": "Austin", + "region": { + "code": "TX", + "label": "Texas" + }, + "postcode": "78758", + "telephone": "5551234567", + "country": { + "code": "US", + "label": "US" + }, + "uid": "MQ==" + } + ] + } + } + } +} +``` + +### Assign a company address (B2B) + + + +[SaaS only](https://experienceleague.adobe.com/en/docs/commerce/user-guides/product-solutions) + + + +The `company_address_id` field is part of the B2B Storefront Compatibility Package and is available with [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview), and with [Adobe Commerce Optimizer](https://experienceleague.adobe.com/en/docs/commerce/aco-optimizer-connector/overview) on Adobe Commerce on cloud infrastructure or on-premises. The field references the **company** address book, not the customer's personal address book, and is available only to an authenticated B2B company user whose company has the company address book feature enabled (`is_company_address_book_enabled`); guests cannot use this field. `company_address_id` is a GraphQL-only field with no REST equivalent. Like `customer_address_uid`, the value is a UID-encoded reference, not a raw integer. + +The following example assigns a shipping address from the company's address book by specifying the `company_address_id` value returned by the [`createCompanyAddress`](../../b2b/company/mutations/create-address.md) mutation. + +**Request:** + +```graphql +mutation { + setShippingAddressesOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + shipping_addresses: [ + { + company_address_id: "MjAy" + } + ] + } + ) { + cart { + shipping_addresses { + firstname + lastname + company + street + city + region { + code + label + } + postcode + telephone + country { + code + label + } + company_address_id + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "setShippingAddressesOnCart": { + "cart": { + "shipping_addresses": [ + { + "firstname": "John", + "lastname": "Doe", + "company": "Company name", + "street": [ + "123 Main St" + ], + "city": "Austin", + "region": { + "code": "TX", + "label": "Texas" + }, + "postcode": "78701", + "telephone": "5551234567", + "country": { + "code": "US", + "label": "US" + }, + "company_address_id": "MjAy" + } + ] + } + } + } +} +``` + ## Errors | Error | Description | @@ -135,3 +297,4 @@ mutation { | `Field CartAddressInput.country_code of required type String! was not provided.` | The value specified in the `shipping_addresses`.`country_code` argument is empty. | | `Field SetShippingAddressesOnCartInput.shipping_addresses of required type [ShippingAddressInput]! was not provided.` | The `shipping_addresses` input attribute of type `ShippingAddressInput` is missing. | | `The current user cannot perform operations on cart "XXX"` | An unauthorized user (guest) tried to set a delivery method for an order on behalf of an authorized user (customer), or a customer tried to set a delivery method for an order on behalf of another customer. | +| `Company address book is not enabled for this company.` | The `company_address_id` field was specified, but the customer's company does not have `is_company_address_book_enabled` set. | From a136185c601c916f2bf078c2694f913683b63af4 Mon Sep 17 00:00:00 2001 From: Shantanu Dasgupta Date: Wed, 29 Jul 2026 06:52:58 +0000 Subject: [PATCH 03/10] REST API pages created for Company address CRUD operations --- src/pages/config.md | 8 + src/pages/rest/b2b/company.md | 4 + src/pages/rest/b2b/create-address.md | 180 ++++++++++++++++++++++ src/pages/rest/b2b/delete-address.md | 54 +++++++ src/pages/rest/b2b/set-default-address.md | 129 ++++++++++++++++ src/pages/rest/b2b/update-address.md | 96 ++++++++++++ 6 files changed, 471 insertions(+) create mode 100644 src/pages/rest/b2b/create-address.md create mode 100644 src/pages/rest/b2b/delete-address.md create mode 100644 src/pages/rest/b2b/set-default-address.md create mode 100644 src/pages/rest/b2b/update-address.md diff --git a/src/pages/config.md b/src/pages/config.md index eeae7c9d0..9ee938678 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -62,6 +62,10 @@ - [Manage company users](/rest/b2b/company-users.md) - [Manage company roles](/rest/b2b/roles.md) - [Manage company structures](/rest/b2b/company-structures.md) + - [Create a company address](/rest/b2b/create-address.md) + - [Update a company address](/rest/b2b/update-address.md) + - [Delete a company address](/rest/b2b/delete-address.md) + - [Set a company address as default](/rest/b2b/set-default-address.md) - [Company credit](/rest/b2b/company-credit.md) - [Manage company credit](/rest/b2b/credit-manage.md) - [Shared catalog](/rest/b2b/shared-catalog.md) @@ -257,13 +261,17 @@ - [Mutations](/graphql/schema/b2b/company/mutations/index.md) - [assignChildCompany](/graphql/schema/b2b/company/mutations/assign-child-company.md) - [createCompany](/graphql/schema/b2b/company/mutations/create.md) + - [createCompanyAddress](/graphql/schema/b2b/company/mutations/create-address.md) - [createCompanyRole](/graphql/schema/b2b/company/mutations/create-role.md) - [createCompanyTeam](/graphql/schema/b2b/company/mutations/create-team.md) - [createCompanyUser](/graphql/schema/b2b/company/mutations/create-user.md) + - [deleteCompanyAddress](/graphql/schema/b2b/company/mutations/delete-address.md) - [deleteCompanyRole](/graphql/schema/b2b/company/mutations/delete-role.md) - [deleteCompanyTeam](/graphql/schema/b2b/company/mutations/delete-team.md) - [deleteCompanyUser](/graphql/schema/b2b/company/mutations/delete-user.md) + - [setDefaultCompanyAddress](/graphql/schema/b2b/company/mutations/set-default-address.md) - [updateCompany](/graphql/schema/b2b/company/mutations/update.md) + - [updateCompanyAddress](/graphql/schema/b2b/company/mutations/update-address.md) - [unassignChildCompany](/graphql/schema/b2b/company/mutations/unassign-child-company.md) - [updateCompanyRole](/graphql/schema/b2b/company/mutations/update-role.md) - [updateCompanyStructure](/graphql/schema/b2b/company/mutations/update-structure.md) diff --git a/src/pages/rest/b2b/company.md b/src/pages/rest/b2b/company.md index 1a6150eb1..53c78c4a4 100644 --- a/src/pages/rest/b2b/company.md +++ b/src/pages/rest/b2b/company.md @@ -18,3 +18,7 @@ The `Company` module allows multiple buyers that belong to the same company to v - [Manage company users](company-users.md) - [Manage company roles](roles.md) - [Manage company structures](company-structures.md) +- [Create a company address](create-address.md) +- [Update a company address](update-address.md) +- [Delete a company address](delete-address.md) +- [Set a company address as default](set-default-address.md) diff --git a/src/pages/rest/b2b/create-address.md b/src/pages/rest/b2b/create-address.md new file mode 100644 index 000000000..f0b22df1b --- /dev/null +++ b/src/pages/rest/b2b/create-address.md @@ -0,0 +1,180 @@ +--- +title: Create a company address +description: Describes the REST endpoint used to create a company address. +keywords: + - B2B + - REST +--- + + + +# Create a company address + +This endpoint creates a new billing or shipping address for a company using the `saveForCompany` operation of the `companyAddressRepositoryV1` service. + + + +This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::add` ACL resource. + +**Service Name:** + +`companyAddressRepositoryV1` + +**REST Endpoint:** + +```text +POST /V1/company/:companyId/address +``` + +**CompanyAddressInterface Parameters:** + +The following table lists the parameters defined in `CompanyAddressInterface`. + +| Name | Description | Format | Requirements | +| --- | --- | --- | --- | +| `company_address_id` | System-generated address ID | integer | Read only. Omit on create. | +| `company_id` | The ID of the company the address belongs to | integer | Optional. Derived from the `:companyId` path parameter. | +| `type` | `1` - Billing\
`2` - Shipping | integer | Required to create an address. | +| `nickname` | A friendly label for the address | string | Optional | +| `firstname` | Contact first name | string | Required | +| `lastname` | Contact last name | string | Required | +| `middlename` | Contact middle name | string | Optional | +| `prefix` | Name prefix (e.g. `Mr.`) | string | Optional | +| `suffix` | Name suffix (e.g. `Jr.`) | string | Optional | +| `company` | Company name shown on the address | string | Required only if configured as a required attribute. | +| `street` | Street address lines | Array[string] | Required. The first line must not be empty. | +| `city` | City | string | Required | +| `country_id` | Two-letter ISO country code | string | Required. Must be an allowed country for the store. | +| `region_id` | Directory region ID | integer | Optional. When provided, `region` is resolved automatically. | +| `region` | Resolved region information | Object | Read only in the response. Contains `region_id`, `region`, and `region_code`. | +| `postcode` | ZIP or postal code | string | Required unless the country has an optional ZIP code. | +| `telephone` | Contact phone number | string | Required only if configured as a required attribute. | +| `fax` | Contact fax number | string | Required only if configured as a required attribute. | +| `vat_id` | VAT identification number | string | Optional | +| `custom_attributes` | Custom EAV attributes for company addresses | Array[Object] | Optional | + +## Create a company address (billing) + +The following example creates a billing address for company `2`. + +**Sample Usage:** + +`POST /rest//V1/company/2/address` + + + +#### Payload + +```json +{ + "companyAddress": { + "type": 1, + "nickname": "HQ Billing", + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": [ + "123 Main St" + ], + "city": "Austin", + "country_id": "US", + "region_id": 57, + "postcode": "78701", + "telephone": "5551234567" + } +} +``` + +#### Response + +```json +{ + "company_address_id": 12, + "company_id": 2, + "type": 1, + "nickname": "HQ Billing", + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": [ + "123 Main St" + ], + "city": "Austin", + "country_id": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78701", + "telephone": "5551234567", + "custom_attributes": [] +} +``` + +## Create a company address (shipping) + +The following example creates a shipping address for the same company. + +**Sample Usage:** + +`POST /rest//V1/company/2/address` + + + +#### Payload + +```json +{ + "companyAddress": { + "type": 2, + "nickname": "Warehouse", + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": [ + "500 Distribution Way" + ], + "city": "Austin", + "country_id": "US", + "region_id": 57, + "postcode": "78702", + "telephone": "5551234567" + } +} +``` + +#### Response + +```json +{ + "company_address_id": 13, + "company_id": 2, + "type": 2, + "nickname": "Warehouse", + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": [ + "500 Distribution Way" + ], + "city": "Austin", + "country_id": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78702", + "telephone": "5551234567", + "custom_attributes": [] +} +``` + +## Notes + +- `type` is required when creating an address and cannot be changed afterward. +- The company address book must be enabled for the company (`is_company_address_book_enabled`), or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` +- Missing required fields (e.g. `firstname`) return `400 Bad Request` with a message identifying the missing field. diff --git a/src/pages/rest/b2b/delete-address.md b/src/pages/rest/b2b/delete-address.md new file mode 100644 index 000000000..0898deaef --- /dev/null +++ b/src/pages/rest/b2b/delete-address.md @@ -0,0 +1,54 @@ +--- +title: Delete a company address +description: Describes the REST endpoint used to delete an existing company address. +keywords: + - B2B + - REST +--- + + + +# Delete a company address + +This endpoint deletes an existing company address using the `deleteById` operation of the `companyAddressRepositoryV1` service. + + + +This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::delete` ACL resource. + +**Service Name:** + +`companyAddressRepositoryV1` + +**REST Endpoint:** + +```text +DELETE /V1/company-address/:addressId +``` + +## Delete a company address + +The following example deletes company address `12`. + +**Sample Usage:** + +`DELETE /rest//V1/company-address/12` + + + +#### Payload + +```json +// none +``` + +#### Response + +```json +// `true`, indicating the request was successful +``` + +## Notes + +- A subsequent `GET /V1/company-address/12` returns `404 Not Found` after the address is deleted. +- Deleting an address that does not exist returns `404 Not Found`. diff --git a/src/pages/rest/b2b/set-default-address.md b/src/pages/rest/b2b/set-default-address.md new file mode 100644 index 000000000..487292d9b --- /dev/null +++ b/src/pages/rest/b2b/set-default-address.md @@ -0,0 +1,129 @@ +--- +title: Set a company address as default +description: Describes the REST endpoint used to set a company address as the default billing or shipping address. +keywords: + - B2B + - REST +--- + + + +# Set a company address as default + +This endpoint sets a company address as the default billing or shipping address for its company, using the `setDefaultByAddressId` operation of the `companyDefaultAddressManagementV1` service. The address type (billing or shipping) is determined by the address itself, so the same endpoint is used for both. + + + +This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::default` ACL resource. + +**Service Name:** + +`companyDefaultAddressManagementV1` + +**REST Endpoint:** + +```text +PUT /V1/company-addresses/:addressId/default +``` + +## Set a billing address as default + +The following example sets billing address `12` as the default billing address for its company. + +**Sample Usage:** + +`PUT /rest//V1/company-addresses/12/default` + + + +#### Payload + +```json +// none +``` + +#### Response + +```json +{ + "company_address_id": 12, + "company_id": 2, + "type": 1, + "nickname": "HQ Billing", + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": [ + "123 Main St" + ], + "city": "Austin", + "country_id": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78701", + "telephone": "5551234567", + "custom_attributes": [] +} +``` + +## Set a shipping address as default + +The following example sets shipping address `13` as the default shipping address for its company. + +**Sample Usage:** + +`PUT /rest//V1/company-addresses/13/default` + + + +#### Payload + +```json +// none +``` + +#### Response + +```json +{ + "company_address_id": 13, + "company_id": 2, + "type": 2, + "nickname": "Warehouse", + "firstname": "John", + "lastname": "Doe", + "company": "Acme Corp", + "street": [ + "500 Distribution Way" + ], + "city": "Austin", + "country_id": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "78702", + "telephone": "5551234567", + "custom_attributes": [] +} +``` + +## Read the default addresses for a company + +After setting defaults, you can read them from the company's default billing and shipping endpoints: + +```text +GET /V1/companies/:companyId/billingAddress +GET /V1/companies/:companyId/shippingAddress +``` + +## Notes + +- The company address book must be enabled for the company, or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` +- Requesting the default billing or shipping address for a company that has none configured returns `404 Not Found` with the message `Default company address not found`. diff --git a/src/pages/rest/b2b/update-address.md b/src/pages/rest/b2b/update-address.md new file mode 100644 index 000000000..3ff43e4a7 --- /dev/null +++ b/src/pages/rest/b2b/update-address.md @@ -0,0 +1,96 @@ +--- +title: Update a company address +description: Describes the REST endpoint used to update an existing company address. +keywords: + - B2B + - REST +--- + + + +# Update a company address + +This endpoint updates an existing company address using the `saveByAddressId` operation of the `companyAddressRepositoryV1` service. + + + +This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::edit` ACL resource. + +**Service Name:** + +`companyAddressRepositoryV1` + +**REST Endpoint:** + +```text +PUT /V1/company-address/:addressId +``` + +See [Create a company address](create-address.md) for the full list of `CompanyAddressInterface` parameters. + +## Update a company address + +The following example updates the contact and street details of an existing address. + +**Sample Usage:** + +`PUT /rest//V1/company-address/12` + + + +#### Payload + +```json +{ + "companyAddress": { + "company_id": 2, + "nickname": "Updated Nickname", + "firstname": "Jane", + "lastname": "Smith", + "company": "Updated Corp", + "street": [ + "456 Oak Ave" + ], + "city": "Dallas", + "country_id": "US", + "region_id": 57, + "postcode": "75201", + "telephone": "5559876543" + } +} +``` + +#### Response + +```json +{ + "company_address_id": 12, + "company_id": 2, + "type": 1, + "nickname": "Updated Nickname", + "firstname": "Jane", + "lastname": "Smith", + "company": "Updated Corp", + "street": [ + "456 Oak Ave" + ], + "city": "Dallas", + "country_id": "US", + "region_id": 57, + "region": { + "region_id": 57, + "region": "Texas", + "region_code": "TX" + }, + "postcode": "75201", + "telephone": "5559876543", + "custom_attributes": [] +} +``` + +## Notes + +- `type` is omitted from the payload above; when `type` is left out, the address keeps its existing type. Passing a `type` value that differs from the address's current type returns `400 Bad Request`. +- If `company_id` is included in the payload, it must match the company that already owns the address, or the request fails with `400 Bad Request` and the message `The company address does not belong to the specified company.` +- The company address book must be enabled for the company, or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` +- Clearing the default flag on the currently-default address is not handled here; use [Set a company address as default](set-default-address.md) to change which address is default. From 07ef04677dd6dd8d84de5c9d704b09eed793aa37 Mon Sep 17 00:00:00 2001 From: Shantanu Dasgupta Date: Wed, 29 Jul 2026 07:46:30 +0000 Subject: [PATCH 04/10] Updated REST API for company --- src/pages/rest/b2b/company-object.md | 118 +++++++++++++++++++++++++-- 1 file changed, 111 insertions(+), 7 deletions(-) diff --git a/src/pages/rest/b2b/company-object.md b/src/pages/rest/b2b/company-object.md index bf87e777a..7056b8325 100644 --- a/src/pages/rest/b2b/company-object.md +++ b/src/pages/rest/b2b/company-object.md @@ -53,9 +53,22 @@ The following table lists the parameters defined in `CompanyInterface`. | `rejected_at` | A timestamp indicating when the company was rejected. | string | Optional | | `super_user_id` | The `customer_id` of the company administrator. When creating a company, the `customer_id` must already exist. | integer | Required to create or update a company. | +**Company Address Book Extension Attributes:** + +The B2B Storefront Compatibility Package's `CompanyAddressStorefrontCompatibilityRest` module adds the following extension attributes to `CompanyInterface`. They can be set in the `extension_attributes` object of `POST` and `PUT` requests, and are always returned in the `extension_attributes` object of `GET` requests. + + + +`is_company_address_book_enabled` and `is_custom_shipping_address_allowed` are part of the B2B Storefront Compatibility Package and are only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + +| Name | Description | Format | Requirements | +| --- | --- | --- | --- | +| `is_company_address_book_enabled` | Whether company users can manage the company's own address book. See [Create a company address](create-address.md). | boolean | Optional. Defaults to `false` for a new company. | +| `is_custom_shipping_address_allowed` | Whether company users can enter a custom shipping address at checkout instead of selecting one from the company address book. Automatically saved as `false` whenever `is_company_address_book_enabled` is `false`, regardless of the value sent in the request. | boolean | Optional. Defaults to `false` for a new company. | + ## Create a company -The following example creates a company and assigns the default shared catalog (`customer_group_id`). The company admin (`super_user_id`) must be a previously-defined `customer_id`. +The following example creates a company and assigns the default shared catalog (`customer_group_id`). The company admin (`super_user_id`) must be a previously-defined `customer_id`. This example also enables the company's address book (`is_company_address_book_enabled`) and allows custom shipping addresses at checkout (`is_custom_shipping_address_allowed`). **Sample Usage:** @@ -80,7 +93,11 @@ The following example creates a company and assigns the default shared catalog ( "postcode": "99999", "telephone": "4155551212", "super_user_id": 5, - "customer_group_id": 1 + "customer_group_id": 1, + "extension_attributes": { + "is_company_address_book_enabled": true, + "is_custom_shipping_address_allowed": true + } } } ``` @@ -110,7 +127,9 @@ The following example creates a company and assigns the default shared catalog ( "quote_config": { "company_id": "2", "is_quote_enabled": false - } + }, + "is_company_address_book_enabled": true, + "is_custom_shipping_address_allowed": true } } ``` @@ -145,7 +164,11 @@ The following call changes the company status to Rejected (`2`) and explains why "telephone": "4155551212", "super_user_id": 5, "status": 2, - "reject_reason": "Failed background check." + "reject_reason": "Failed background check.", + "extension_attributes": { + "is_company_address_book_enabled": true, + "is_custom_shipping_address_allowed": true + } } } ``` @@ -175,11 +198,84 @@ The following call changes the company status to Rejected (`2`) and explains why "quote_config": { "company_id": "2", "is_quote_enabled": true + }, + "is_company_address_book_enabled": true, + "is_custom_shipping_address_allowed": true + } +} +``` + +## Disable a company's address book + +The following example disables the company address book for company `2`. Even though the request also sends `is_custom_shipping_address_allowed` as `true`, Adobe Commerce always saves it as `false` whenever `is_company_address_book_enabled` is `false`. + +**Sample Usage:** + +`PUT /rest//V1/company/2` + + + +#### Payload + +```json +{ + "company": { + "id": 2, + "company_name": "Test company", + "company_email": "newemail@example.com", + "customer_group_id": 1, + "street":[ + "100 Big Tree Avenue" + ], + "city": "San Francisco", + "country_id": "US", + "region": "CA", + "region_id": "12", + "postcode": "99999", + "telephone": "4155551212", + "super_user_id": 5, + "extension_attributes": { + "is_company_address_book_enabled": false, + "is_custom_shipping_address_allowed": true } } } ``` +#### Response + +```json +{ + "id": 2, + "company_name": "Test company", + "company_email": "newemail@example.com", + "street": [ + "100 Big Tree Avenue" + ], + "city": "San Francisco", + "country_id": "US", + "region": "California", + "region_id": "12", + "postcode": "99999", + "telephone": "4155551212", + "customer_group_id": 1, + "sales_representative_id": 1, + "reject_reason": null, + "rejected_at": null, + "super_user_id": 5, + "extension_attributes": { + "quote_config": { + "company_id": "2", + "is_quote_enabled": true + }, + "is_company_address_book_enabled": false, + "is_custom_shipping_address_allowed": false + } +} +``` + +`is_custom_shipping_address_allowed` is forced to `false` in the saved config and in the response, regardless of the value sent in the request, whenever `is_company_address_book_enabled` is `false`. Once the address book is disabled, requests to [create](create-address.md), [update](update-address.md), [delete](delete-address.md), or [set the default](set-default-address.md) company addresses return `400 Bad Request` with the message `Company address book is not enabled for this company.` + ## Return all information about a company This call returns detailed information about the specified company. @@ -221,11 +317,15 @@ This call returns detailed information about the specified company. "quote_config": { "company_id": "2", "is_quote_enabled": true - } + }, + "is_company_address_book_enabled": false, + "is_custom_shipping_address_allowed": false } } ``` +`GET` requests always include `is_company_address_book_enabled` and `is_custom_shipping_address_allowed` in `extension_attributes`, defaulting to `false` for a company that has never had these values set. + ## Delete a company When you delete a company, Adobe Commerce assigns the "Inactive" status to all company members. The system also removes company ID from the customer profile of all company members. @@ -297,7 +397,9 @@ See [Search using REST APIs](../use-rest/performing-searches.md) for information "use_config_settings": 1, "quote_config": { "is_quote_enabled": true - } + }, + "is_company_address_book_enabled": false, + "is_custom_shipping_address_allowed": false } }, { @@ -327,7 +429,9 @@ See [Search using REST APIs](../use-rest/performing-searches.md) for information "use_config_settings": 1, "quote_config": { "is_quote_enabled": true - } + }, + "is_company_address_book_enabled": true, + "is_custom_shipping_address_allowed": true } } ], From 0367d099e8af3f94e1cf653fb189ee699188a8ef Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 31 Jul 2026 12:42:13 -0500 Subject: [PATCH 05/10] Apply suggestions from code review --- src/pages/rest/b2b/create-address.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/rest/b2b/create-address.md b/src/pages/rest/b2b/create-address.md index f0b22df1b..059684381 100644 --- a/src/pages/rest/b2b/create-address.md +++ b/src/pages/rest/b2b/create-address.md @@ -53,7 +53,7 @@ The following table lists the parameters defined in `CompanyAddressInterface`. | `vat_id` | VAT identification number | string | Optional | | `custom_attributes` | Custom EAV attributes for company addresses | Array[Object] | Optional | -## Create a company address (billing) +## Create a company billing address The following example creates a billing address for company `2`. @@ -113,7 +113,7 @@ The following example creates a billing address for company `2`. } ``` -## Create a company address (shipping) +## Create a company shipping address The following example creates a shipping address for the same company. From 5eb3fb4b8c9d84a3d42c39906523de4236d46e42 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 31 Jul 2026 13:16:53 -0500 Subject: [PATCH 06/10] Enhance create-address documentation with requirements --- src/pages/rest/b2b/create-address.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/src/pages/rest/b2b/create-address.md b/src/pages/rest/b2b/create-address.md index 059684381..0ecab086d 100644 --- a/src/pages/rest/b2b/create-address.md +++ b/src/pages/rest/b2b/create-address.md @@ -10,12 +10,16 @@ keywords: # Create a company address -This endpoint creates a new billing or shipping address for a company using the `saveForCompany` operation of the `companyAddressRepositoryV1` service. - This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::add` ACL resource. +This endpoint creates a new billing or shipping address for a company using the `saveForCompany` operation of the `companyAddressRepositoryV1` service. + +The company address book must be enabled for the company (`is_company_address_book_enabled`), or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` + +Missing required fields (for example, `firstname`) return `400 Bad Request` with a message identifying the missing field. + **Service Name:** `companyAddressRepositoryV1` @@ -34,7 +38,7 @@ The following table lists the parameters defined in `CompanyAddressInterface`. | --- | --- | --- | --- | | `company_address_id` | System-generated address ID | integer | Read only. Omit on create. | | `company_id` | The ID of the company the address belongs to | integer | Optional. Derived from the `:companyId` path parameter. | -| `type` | `1` - Billing\
`2` - Shipping | integer | Required to create an address. | +| `type` | `1` - Billing\
`2` - Shipping | integer | Required to create an address. The value cannot be changed afterward.| | `nickname` | A friendly label for the address | string | Optional | | `firstname` | Contact first name | string | Required | | `lastname` | Contact last name | string | Required | @@ -172,9 +176,3 @@ The following example creates a shipping address for the same company. "custom_attributes": [] } ``` - -## Notes - -- `type` is required when creating an address and cannot be changed afterward. -- The company address book must be enabled for the company (`is_company_address_book_enabled`), or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` -- Missing required fields (e.g. `firstname`) return `400 Bad Request` with a message identifying the missing field. From 2d22c13e4b0947701331d219ae15f7e0c7f54307 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 31 Jul 2026 13:18:49 -0500 Subject: [PATCH 07/10] Place note at top --- src/pages/rest/b2b/delete-address.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/rest/b2b/delete-address.md b/src/pages/rest/b2b/delete-address.md index 0898deaef..e0f140d87 100644 --- a/src/pages/rest/b2b/delete-address.md +++ b/src/pages/rest/b2b/delete-address.md @@ -10,12 +10,12 @@ keywords: # Delete a company address -This endpoint deletes an existing company address using the `deleteById` operation of the `companyAddressRepositoryV1` service. - This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::delete` ACL resource. +This endpoint deletes an existing company address using the `deleteById` operation of the `companyAddressRepositoryV1` service. + **Service Name:** `companyAddressRepositoryV1` From 2e935a736526e96f1572ee9bef19be7f52ee17a8 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 31 Jul 2026 13:20:27 -0500 Subject: [PATCH 08/10] Place note at top --- src/pages/rest/b2b/set-default-address.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/rest/b2b/set-default-address.md b/src/pages/rest/b2b/set-default-address.md index 487292d9b..81c365bf0 100644 --- a/src/pages/rest/b2b/set-default-address.md +++ b/src/pages/rest/b2b/set-default-address.md @@ -10,12 +10,12 @@ keywords: # Set a company address as default -This endpoint sets a company address as the default billing or shipping address for its company, using the `setDefaultByAddressId` operation of the `companyDefaultAddressManagementV1` service. The address type (billing or shipping) is determined by the address itself, so the same endpoint is used for both. - This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::default` ACL resource. +This endpoint sets a company address as the default billing or shipping address for its company, using the `setDefaultByAddressId` operation of the `companyDefaultAddressManagementV1` service. The address type (billing or shipping) is determined by the address itself, so the same endpoint is used for both. + **Service Name:** `companyDefaultAddressManagementV1` From a21096514af23c675a00c8661c3d25c02f15d43c Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 31 Jul 2026 13:29:14 -0500 Subject: [PATCH 09/10] Enhance update-address documentation with details Clarified the update process for company addresses, including conditions for `company_id` and `type` fields. --- src/pages/rest/b2b/update-address.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/src/pages/rest/b2b/update-address.md b/src/pages/rest/b2b/update-address.md index 3ff43e4a7..7fbf82d97 100644 --- a/src/pages/rest/b2b/update-address.md +++ b/src/pages/rest/b2b/update-address.md @@ -10,12 +10,18 @@ keywords: # Update a company address -This endpoint updates an existing company address using the `saveByAddressId` operation of the `companyAddressRepositoryV1` service. - This endpoint is part of the B2B Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). Requests require an admin or integration token whose role includes the `Magento_CompanyAddressStorefrontCompatibility::edit` ACL resource. +This endpoint updates an existing company address using the `saveByAddressId` operation of the `companyAddressRepositoryV1` service. The company address book must be enabled for the company, or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` + +You cannot specify the `type` field in the company address payload. Passing a `type` value that differs from the address's current type returns `400 Bad Request`. + +If `company_id` is included in the payload, it must match the company that already owns the address, or the request fails with `400 Bad Request` and the message `The company address does not belong to the specified company.` + +Clearing the default flag on the currently-default address is not handled here; use [Set a company address as default](set-default-address.md) to change which address is default. + **Service Name:** `companyAddressRepositoryV1` @@ -87,10 +93,3 @@ The following example updates the contact and street details of an existing addr "custom_attributes": [] } ``` - -## Notes - -- `type` is omitted from the payload above; when `type` is left out, the address keeps its existing type. Passing a `type` value that differs from the address's current type returns `400 Bad Request`. -- If `company_id` is included in the payload, it must match the company that already owns the address, or the request fails with `400 Bad Request` and the message `The company address does not belong to the specified company.` -- The company address book must be enabled for the company, or the request fails with `400 Bad Request` and the message `Company address book is not enabled for this company.` -- Clearing the default flag on the currently-default address is not handled here; use [Set a company address as default](set-default-address.md) to change which address is default. From 2807547bcd359a935e689529c9ae66e059376a92 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 31 Jul 2026 13:55:49 -0500 Subject: [PATCH 10/10] Linting errors --- .../graphql/schema/b2b/company/mutations/create-address.md | 2 -- src/pages/graphql/schema/b2b/company/mutations/index.md | 2 +- .../schema/b2b/company/mutations/set-default-address.md | 5 +++-- .../graphql/schema/b2b/company/mutations/update-address.md | 3 ++- src/pages/graphql/schema/b2b/company/queries/company.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/pages/graphql/schema/b2b/company/mutations/create-address.md b/src/pages/graphql/schema/b2b/company/mutations/create-address.md index 7e3f9e91e..4a4b794f4 100644 --- a/src/pages/graphql/schema/b2b/company/mutations/create-address.md +++ b/src/pages/graphql/schema/b2b/company/mutations/create-address.md @@ -251,5 +251,3 @@ mutation CreateCompanyAddress { | `Company context is required.` | Missing `X-Adobe-Company` header | | `Company address book is not enabled for this company.` | Address book disabled for company | | `You do not have authorization to perform this action.` | Missing add or set-default ACL | - - diff --git a/src/pages/graphql/schema/b2b/company/mutations/index.md b/src/pages/graphql/schema/b2b/company/mutations/index.md index 4a2adca8a..833dfc0b9 100644 --- a/src/pages/graphql/schema/b2b/company/mutations/index.md +++ b/src/pages/graphql/schema/b2b/company/mutations/index.md @@ -23,4 +23,4 @@ The B2B company mutations allow you to perform the management operations: The company address book mutations allow you to perform the company address management operations: * Create, update and delete a company address. -* Set default company billing or shipping address. \ No newline at end of file +* Set default company billing or shipping address. diff --git a/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md b/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md index 885451d35..fa23c93f0 100644 --- a/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md +++ b/src/pages/graphql/schema/b2b/company/mutations/set-default-address.md @@ -65,7 +65,8 @@ mutation SetDefaultCompanyAddress { } } } -``` + + **Response (Shipping):** ```json @@ -92,4 +93,4 @@ After setting defaults, you can read them from the Company type: default_shipping_address { id address_type is_default } } } -``` \ No newline at end of file +`` diff --git a/src/pages/graphql/schema/b2b/company/mutations/update-address.md b/src/pages/graphql/schema/b2b/company/mutations/update-address.md index c0cb27865..6dfeb9c69 100644 --- a/src/pages/graphql/schema/b2b/company/mutations/update-address.md +++ b/src/pages/graphql/schema/b2b/company/mutations/update-address.md @@ -99,4 +99,5 @@ mutation UpdateCompanyAddress { } } ``` -Clearing default via `is_default`: false on an address that is currently default requires set-default ACL (same as setDefaultCompanyAddress). \ No newline at end of file + +Clearing default via `is_default`: false on an address that is currently default requires set-default ACL (same as setDefaultCompanyAddress). diff --git a/src/pages/graphql/schema/b2b/company/queries/company.md b/src/pages/graphql/schema/b2b/company/queries/company.md index cb0c94ca6..465ee8f4c 100644 --- a/src/pages/graphql/schema/b2b/company/queries/company.md +++ b/src/pages/graphql/schema/b2b/company/queries/company.md @@ -511,4 +511,4 @@ query{ } } } -``` \ No newline at end of file +```