update_address

Edits one of the user’s saved addresses. Only two kinds of edit are allowed: change tag alone (relabel; the delivery target stays put), or suggestion_token + address_detail to change the location / unit detail (the gateway re-registers the address upstream with the new POI and repoints the same row to it). Recipient name / phone are not editable here (use select_address for that). The address_id stays the same.

Address flow: search_addresses to find a place → suggestion token → select_address to save the address → address_id → update_address to edit a saved address. Before changing the location / detail you must call search_addresses to get a suggestion_token for the new place: upstream only honours a registered delivery address, so a move is a re-registration, not a text edit.

Two kinds of edit:

Change tag only (no suggestion_token) → the label is updated directly; the delivery target is untouched. If address_detail differs from the current value and is non-blank, this returns ADDRESS_UPDATE_REQUIRES_TOKEN.
Pass suggestion_token + address_detail → the delivery address is re-registered upstream with the new POI, reusing the row’s existing recipient, and the same row’s location / detail are overwritten; address_id and recipient stay stable. A blank address_detail here returns DETAIL_REQUIRED.

Parameters

Parameter	Type	Required	Default	Description
`consent_grant_id`	string	Yes	—	User consent grant ID (`cg_` prefix, from `verify_user_bind`), identifying the consenting user
`address_id`	string	Yes	—	ID of the saved address to edit; use the `address_id` returned by `select_address` as-is
`suggestion_token`	string \| null	No	`null`	Address suggestion token (from `search_addresses`). Required to change the location / detail; omit when only changing `tag`
`address_detail`	string \| null	No	`null`	New apartment / floor / room number. Required and non-blank when `suggestion_token` is given
`tag`	string \| null	No	`null`	New label — `home` / `work` / `school` / empty string

Returns

Field	Type	Description
`address_id`	string	Gateway address ID (`addr_` prefix); unchanged after the update, can be passed directly to `preview_order` etc.
`display_name`	string	Address display name (the newly selected POI’s name after a re-registration)
`address_detail`	string	Door number / floor details
`city`	string	City name (e.g. “武汉”). Older addresses may return an empty string, meaning unknown — not a different city.
`lat`	number \| null	Latitude
`lng`	number \| null	Longitude
`contact_name`	string \| null	Recipient name (not editable here; carried over from the original)
`contact_phone_masked`	string \| null	Masked recipient phone (display only; the plaintext is never returned)

Error Codes

code	Description
`CONSENT_GRANT_REQUIRED`	Missing consent grant (no `consent_grant_id`)
`CONSENT_GRANT_INVALID`	Consent grant is invalid
`CONSENT_GRANT_EXPIRED`	Consent grant has expired; re-authorization required
`CAP_NOT_BOUND`	The delivery capability is not enabled for this agent
`CONSENT_GRANT_WRONG_CAP`	Consent grant belongs to a different capability / provider
`PUBLIC_REFERENCE_INVALID`	`address_id` is invalid, expired, or does not belong to the consenting user
`ADDRESS_UPDATE_REQUIRES_TOKEN`	Changing location / detail without a `suggestion_token`; not needed for `tag`-only edits
`DETAIL_REQUIRED`	`suggestion_token` was given but `address_detail` is empty / blank
`SUGGESTION_EXPIRED`	`suggestion_token` is invalid or expired; re-run `search_addresses`
`ADDRESS_CREATE_REJECTED`	The platform refused to re-register the address at the new location (business reason). Retry with a different suggestion
`ELEME_ERROR`	Upstream Eleme / Taobao Instant returned an error (e.g. re-registering the address failed)

See Error Handling for the full list.

Example Call

Change the label only:

{
  "name": "update_address",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "address_id": "<from select_address>",
    "tag": "home"
  }
}

Change the location / detail (search first):

{
  "name": "update_address",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "address_id": "<from select_address>",
    "suggestion_token": "<token from search_addresses>",
    "address_detail": "Building 3, Room 101"
  }
}

Overview

Integration

Guides

Authorization

Shops

Addresses

Order

Payment

update_address

update_address

Parameters

Returns

Error Codes

Example Call

​update_address

​Parameters

​Returns

​Error Codes

​Example Call

update_address

Parameters

Returns

Error Codes

Example Call