v50

latestOpenAPI 3.0.0raw.githubusercontent.com2026-05-142616180.5 KB

Addresses

Update address by ID

This endpoint allows you to update an existing address document in the AD data entity. Partially updates a customer address.

⚠️ When updating addresses you must send each field according to the specifications provided. Otherwise, the Checkout module will not be able to autofill data during the shopping flow, which can block the purchase. Learn more about SmartCheckout - Customer information automatic fill-in.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code 403 error. These are the applicable resources for this endpoint:

Product	Category	Resource
Dynamic Storage	Dynamic storage generic resources	Insert or update document (not remove)
Dynamic Storage	Dynamic storage generic resources	Full access to all documents
Dynamic Storage	Dynamic storage generic resources	Master Data administrator

There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.

❗ To prevent integrations from having excessive permissions, consider the best practices for managing API keys when assigning License Manager roles to integrations.

patch/api/dataentities/AD/documents/{addressId}

Path parameters

addressIdstring required

ID of the address to update.

Query parameters

_schemastring

Example:schema

Name of the schema that the document complies with. This field is required when using _where or _fields query parameters.

Headers

Content-Typestring required

Type of the content being sent.

Acceptstring required

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Request body

addressNamestring nullable

Address name.

addressLabelstring nullable

Custom label for the address used by shoppers and buyer org managers.

addressType'commercial' | 'invoice' nullable

Type of address. For example, Residential or Pickup, among others. For B2B Buyer Portal, this field is required and its possible values are commercial for shipping or invoice for billing.

receiverNamestring nullable

Name of the person who is going to receive orders at this address. This field is required for B2B Buyer Portal.

citystring nullable

City of the shipping address. This field is required for B2B Buyer Portal.

statestring nullable

State of the shipping address. The state or province of the address. This field is required for B2B Buyer Portal.

countrystring nullable

Three letter ISO code of the country of the shipping address. This field is required for B2B Buyer Portal.

postalCodestring nullable

Postal Code. The format must be compatible with the country postal code format (e.g., 00000 for addresses in the USA). This field is required for B2B Buyer Portal.

streetstring nullable

The street name of the address. This field is required for B2B Buyer Portal.

numberstring nullable

Number of the building, house or apartment in the shipping address. This field is required for B2B Buyer Portal.

neighborhoodstring nullable

Neighborhood of the address.

complementstring nullable

Additional information or details that help identify or locate the shipping address, such as apartment number, suite, floor, or unit (if applicable).

referencestring nullable

Optional reference point or nearby landmark to help locate the shipping address during delivery (e.g., next to a park or behind a building).

geoCoordinatestring nullable

The geographical coordinates of the address (optional). This field is recommended for B2B Buyer Portal.

userIdstring nullable

ID of the customer to whom the address belongs. This information is the id returned by the customer profile (or contract) creation request. This field is required for B2B Buyer Portal.

Example request

{
  "addressName": "My house",
  "addressLabel": "NC Office",
  "addressType": "commercial",
  "receiverName": "Clark Kent.",
  "city": "Raleigh",
  "state": "NC",
  "country": "USA",
  "postalCode": "12345",
  "street": "Main Street",
  "number": "300",
  "neighborhood": "Downtown",
  "complement": "3rd floor",
  "reference": "Next to the park",
  "geoCoordinate": "40.7128,-74.0060",
  "userId": "7e03m794-a33a-11e9-84rt6-0adfa64s5a8e"
}

Response

Idstring required

ID of the document that was created or updated.

Hrefstring required

Document reference URL.