Updating an Order’s Shipping Address via API

This API lets merchants update the shipping address of an existing order in real time. When shoppers change their delivery address on the merchant’s platform, this API synchronizes the change with Global-e’s system.

Key Features

Real-time shipping address updates
Asynchronous processing (HTTP 202 Accepted)
Idempotency support to prevent duplicate updates
Comprehensive address validation
Supports both JWT (recommended) and Merchant-Guid (deprecated) authentication

Prerequisites

Active merchant account with Global-e
Valid authentication credentials (JWT or Merchant-Guid)
Existing and updatable order (not shipped or canceled)
HTTPS connectivity to
https://bglobale.com
UUID v4 generator for the Idempotency-Key

Authentication

Primary authentication (recommended):

Authorization: Bearer {JWT Token}

Alternative (deprecated):

Merchant-Guid: {merchantGuid}

All requests must use HTTPS (TLS 1.2+). The Idempotency-Key must be unique per address change, and authentication credentials must be stored securely and never logged.

Endpoint

Method	URL
PUT	https://bglobale.com/api/v1/orders/shipping-address

Headers

Name	Description
Authorization	JWT Bearer token (required, unless using Merchant-Guid)
Merchant-Guid	Deprecated — use JWT authentication if possible
Idempotency-Key	UUID v4 — unique per request
Content-Type	`application/json`

Example Request Body

{
  "orderId": "1234567890",
  "primaryShipping": {
    "firstName": "John",
    "lastName": "Doe",
    "shippingAddress1": "123 Main Street",
    "countryName": "United States",
    "city": "New York",
    "zipCode": "10001",
    "email": "[email protected]",
    "phone1": "+1-555-123-4567"
  },
  "extraDetails": {
    "customerComments": "Please deliver to reception"
  }
}

Example cURL Command

curl --location --request PUT 'https://bglobale.com/api/v1/orders/shipping-address' \
--header 'Authorization: Bearer {JWT Token}' \
--header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data-raw '{ "orderId": "1234567890", "primaryShipping": { "firstName": "John", "lastName": "Doe", "shippingAddress1": "123 Main Street", "countryName": "United States", "city": "New York", "zipCode": "10001", "email": "[email protected]", "phone1": "+1-555-123-4567" } }'

Responses

202 Accepted — Address change request accepted and processed asynchronously.

Code	Description	Recommended Action
400	Invalid order ID or missing address fields	Verify order ID format and required fields
401	Invalid credentials	Validate JWT or Merchant-Guid
404	Order not found	Confirm that the order exists
409	Idempotency-Key conflict	Generate a new UUID and retry
500	Internal server error	Retry with exponential backoff (2s, 4s, 8s; max 3 attempts)

Best Practices

Generate a new UUID v4 for each unique address update.
Reuse the same Idempotency-Key only for identical retries.
Validate all required fields before sending requests.
Retry only on 5xx or timeout errors.
Do not log authentication headers or tokens.
Do not poll after receiving 202 Accepted — processing is asynchronous.

FAQ

1.	How long does an update take?
	Responses return within ~200 ms; processing occurs asynchronously.
2.	Can I update the same order multiple times?
	Yes, but each request must use a new `Idempotency-Key`.
3.	Are non-Latin characters supported?
	Yes, the API fully supports UTF-8 (including Japanese, Arabic, and Hebrew).
4.	Can I update multiple orders in a single request?
	No, only one order can be updated per request.

Change Log

Version	Date	Notes
1.0	October 2025	Initial API release
1.1	October 2025	Updated to use camelCase fields; increased address field limit to 255 characters

Documentation Portal