BrainerceSet billing address (Storefront)
Sets a billing address that differs from the shipping address. Optional: without it billing defaults to the shipping address. The shipping address must be set first.
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.
When true, the billing address is set identically to the previously-saved shipping address and the address fields on this request are ignored.
curl -X PATCH "https://api.brainerce.com/api/vc/string/checkout/string/billing-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" }'{
"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"
}
}{
"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}/billing-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}/billing-address"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/checkout/{checkoutId}/billing-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}/billing-address"
}