BrainerceSet shipping address
Sets the shipping address of the checkout. The response carries the updated checkout and the shipping rates for that address, so no second call is needed.
For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.
In: header
Path Parameters
Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.
Checkout id, returned by checkout (create checkout).
Query Parameters
Language code, for example he. Used only when no Accept-Language header is sent. A language the store does not support, or the store's default language, returns the default text.
Header Parameters
Origin of the storefront page making the call, for example https://shop.example.com. Required: a request with no Origin header is refused with 403. On a LIVE channel its host must equal the channel's registered domain (or one of its subdomains) or match an allowed origin. A TEST channel with no domain accepts any origin; once a domain is set it is matched as on LIVE.
Preferred language, for example he. Its first tag is used when it is one of the store's supported languages other than the default; translated fields are then returned in that language. Falls back to the locale query parameter.
Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.
Recipient first name.
Recipient last name.
Company / organization name for the address (used on invoices and customs forms).
Primary street address line (street number + street name).
Secondary address line (apartment, suite, unit, building, floor, …).
City / locality.
State / province / region code or name. Required by some shipping carriers (e.g. USPS, UPS) for US/CA/AU addresses. Use the ISO-3166-2 subdivision code when possible (e.g. CA for California).
Postal / ZIP code.
ISO-3166-1 alpha-2 country code (uppercase, 2 letters).
Recipient phone number in E.164 format. Used by carriers for delivery notifications.
Shopper email address. Used for order confirmation, abandoned-checkout recovery, and matching/creating the customer record.
emailWhether the shopper opted in to marketing communications at checkout. When true, the customer record is flagged for marketing email/SMS lists.
Order-level note from the shopper ("Please leave at the door"). Rides along with the address step so single-page checkouts need no extra call. Copied onto the order at completion, then shown to the merchant in the dashboard and included in the confirmation email. Max 2000 chars. Send an empty string to clear a previously-set note.
length <= 2000GA4 gtag.js client_id (from gtag('get', measurementId, 'client_id', cb)), forwarded so the server-side purchase event can stitch to this browser session. Written onto the cart if not already set. Omit if unavailable, and never send a synthesized id.
length <= 100GA4 gtag.js session_id (from gtag('get', measurementId, 'session_id', cb)), forwarded alongside analyticsClientId for the same stitch.
length <= 100Hostname of the external referrer that brought this shopper (last non-direct touch), auto-attached by the storefront SDK from its brainerce_attr capture. Raw host on purpose, because the platform classifies it (AI/organic/social) at read time. Omit if unknown.
length <= 253utm_source of the last non-direct touch, auto-attached alongside trafficReferrerHost.
length <= 150utm_medium of the last non-direct touch.
length <= 150utm_campaign of the last non-direct touch.
length <= 150utm_term of the last non-direct touch.
length <= 150utm_content of the last non-direct touch.
length <= 150Google Ads click id (gclid query param), auto-attached by the storefront SDK. Write-only: never returned from a public GET. Omit if the visit was not Ads-tagged.
length <= 128Google Ads app/cross-device click id (gbraid query param). Write-only: never returned from a public GET.
length <= 128Google Ads web-to-app click id (wbraid query param). Write-only: never returned from a public GET.
length <= 128Path (never the query string) of the page that first captured this attribution snapshot.
length <= 300ISO 8601 timestamp of when the SDK captured this attribution snapshot client-side.
Which consent regime (e.g. Consent Mode v2) was active when the SDK captured this snapshot.
length <= 40Consent Mode analytics_storage consent state captured client-side (client.updateConsent({analytics})), forwarded like the traffic-attribution fields above. Omit when no consent signal has been captured yet — that is NOT the same as false, and must not be inferred. Gates server-side GA4 sends only — see adsUserDataConsentGranted for the separate ad_user_data purpose.
Consent Mode ad_user_data/ad_personalization consent state captured client-side (client.updateConsent({ads})), forwarded independently from analyticsConsentGranted above. Omit when no consent signal has been captured yet — that is NOT the same as false, and must not be inferred. This is the legal basis Google Ads Enhanced Conversions requires before hashed email/phone can be uploaded; never gate that upload on analyticsConsentGranted instead.
The placeId of the autocomplete suggestion the shopper picked (from checkout/address-autocomplete). Send it whenever the address came from the autocomplete: the server re-resolves it to exact rooftop coordinates and matches polygon ("draw on map") shipping zones against those, instead of re-geocoding the typed address lines. Without it, matching falls back to geocoding the text, which is materially less accurate (a same-named street in another city can outrank the right one). Note there is deliberately NO lat/lng field here: zone matching decides which shipping rate is offered and charged, so coordinates are never taken from the caller.
length <= 512The same sessionToken used for the checkout/address-autocomplete calls that produced placeId. Optional: the resolved place is cached server-side for 24h by placeId, so the normal flow (autocomplete → address-details → this call) hits that cache and needs no token. Pass it when you have it so that a cache miss still bills within the original autocomplete session instead of opening a new one.
length <= 200curl -X PATCH "https://api.brainerce.com/api/vc/string/checkout/string/shipping-address?locale=string" \ -H "origin: string" \ -H "accept-language: string" \ -H "X-SDK-Version: string" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Jane", "lastName": "Doe", "line1": "123 Main Street", "city": "San Francisco", "postalCode": "94105", "country": "US", "email": "[email protected]" }'{
"checkout": {
"id": "clchk_abc123",
"status": "PENDING",
"email": "[email protected]",
"customerId": "clcustomer_abc123",
"deliveryType": "shipping",
"pickupLocation": {
"id": "clx1234567890",
"name": "string",
"rateName": "string",
"address": {
"line1": "5 Rothschild",
"line2": "string",
"city": "Tel Aviv",
"region": "string",
"postalCode": "6688218",
"country": "IL"
},
"phone": "string",
"hours": "string",
"instructions": "string",
"price": "0",
"currency": "ILS"
},
"shippingAddress": {
"firstName": "Jane",
"lastName": "Doe",
"company": "string",
"line1": "123 Main St",
"line2": "string",
"city": "San Francisco",
"region": "CA",
"postalCode": "94103",
"country": "US",
"phone": "string"
},
"billingAddress": {
"firstName": "Jane",
"lastName": "Doe",
"company": "string",
"line1": "123 Main St",
"line2": "string",
"city": "San Francisco",
"region": "CA",
"postalCode": "94103",
"country": "US",
"phone": "string"
},
"shippingRateId": "clshippingrate_abc123",
"shippingMethod": {
"id": "clrate_abc123",
"name": "Standard shipping",
"description": "string",
"price": "5.00",
"currency": "USD",
"estimatedDays": 3,
"source": "manual",
"carrier": "ups",
"service": "ground",
"speedTier": "cheapest"
},
"currency": "ILS",
"subtotal": "39.80",
"discountAmount": "0.00",
"ruleDiscountAmount": "0.00",
"appliedRules": [
{
"id": "clx1234567890",
"name": "string",
"type": "PERCENTAGE_OFF",
"discountAmount": "19.99"
}
],
"shippingAmount": "5.00",
"taxAmount": "0",
"taxBreakdown": {
"subtotal": 39.8,
"shippingNet": 5,
"totalTax": 7.16,
"total": 46.96,
"pricesIncludeTax": true,
"breakdown": [
{
"name": "VAT",
"rate": 0.18,
"amount": 7.16,
"taxClassId": "cltxc_abc123",
"taxClassSlug": "reduced",
"rateId": "cltxr_abc123"
}
],
"currency": "ILS"
},
"total": "46.96",
"totalAmount": "46.96",
"surchargeAmount": "0.00",
"appliedSurcharges": [
{
"key": "giftWrap",
"name": "Gift wrapping",
"value": "string",
"amount": "3.00"
}
],
"customFieldValues": {},
"couponCode": "string",
"tenders": [
{
"tenderId": "cltender_abc123",
"amountApplied": "25.00"
}
],
"providerAmountDue": "21.96",
"notes": "string",
"lineItems": [
{
"id": "clx1234567890",
"productId": "clprd_abc123",
"variantId": "clvariant_abc123",
"quantity": 2,
"unitPrice": "19.90",
"discountAmount": "0",
"product": {
"id": "string",
"name": "string",
"sku": "string",
"images": [
{
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
}
],
"isDownloadable": true
},
"variant": {
"id": "string",
"name": "string",
"sku": "string"
},
"notes": "string",
"metadata": {
"bundleOfferId": "string",
"isBundleItem": true,
"triggerProductId": "string",
"orderBumpId": "string",
"isOrderBump": true
},
"customizations": {}
}
],
"itemCount": 3,
"availableShippingRates": [
{
"id": "clrate_abc123",
"name": "Standard shipping",
"description": "string",
"price": "5.00",
"currency": "USD",
"estimatedDays": 3,
"source": "manual",
"carrier": "ups",
"service": "ground",
"speedTier": "cheapest"
}
],
"expiresAt": "2026-01-15T10:30:00.000Z",
"recoveryEmailSentAt": "2026-01-15T10:30:00.000Z",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z",
"reservation": {
"hasReservation": true,
"expiresAt": "2026-01-15T10:30:00.000Z",
"remainingSeconds": 0,
"strategy": "ON_PAYMENT",
"countdownMessage": "string"
},
"presentment": {
"currency": "EUR",
"subtotal": "36.10",
"discountAmount": "0.00",
"shippingAmount": "4.50",
"taxAmount": "7.30",
"surchargeAmount": "0.00",
"total": "47.90",
"fxChargingRate": "0.2612",
"fxBufferPercent": "string"
}
},
"rates": [
{
"id": "clrate_abc123",
"name": "Standard shipping",
"description": "string",
"price": "5.00",
"currency": "USD",
"estimatedDays": 3,
"source": "manual",
"carrier": "ups",
"service": "ground",
"speedTier": "cheapest"
}
]
}{
"statusCode": 400,
"code": "VALIDATION_FAILED",
"message": "name should not be empty, price must be a positive number",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/checkout/{checkoutId}/shipping-address"
}{
"statusCode": 403,
"code": "INSUFFICIENT_SCOPE",
"message": "API key does not have the required scope: products:write",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/checkout/{checkoutId}/shipping-address"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/checkout/{checkoutId}/shipping-address"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/checkout/{checkoutId}/shipping-address"
}