Customers

Save a new address

Add an address to the signed-in shopper’s address book. Setting an address as the default for shipping or billing automatically clears any previous default of the same kind, so there is always at most one default per kind.

Customer-self access. Works with a publishable key (safe from the browser). Provide the shopper’s session token in the x-auth-token header; it must resolve to the customer in the {id} path parameter, otherwise the request returns 403.

POST

customers

{id}

addresses

Save a new address

curl --request POST \
  --url https://api.tybritelabs.com/v1/customers/{id}/addresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <x-auth-token>' \
  --data '
{
  "full_name": "John Doe",
  "line1": "123 Main St",
  "city": "New York",
  "country": "US",
  "address_type": "both",
  "label": "Home",
  "phone": "+14155551234",
  "line2": "Apt 4B",
  "state": "NY",
  "postal_code": "10001",
  "is_default_shipping": false,
  "is_default_billing": false
}
'

import requests

url = "https://api.tybritelabs.com/v1/customers/{id}/addresses"

payload = {
    "full_name": "John Doe",
    "line1": "123 Main St",
    "city": "New York",
    "country": "US",
    "address_type": "both",
    "label": "Home",
    "phone": "+14155551234",
    "line2": "Apt 4B",
    "state": "NY",
    "postal_code": "10001",
    "is_default_shipping": False,
    "is_default_billing": False
}
headers = {
    "x-auth-token": "<x-auth-token>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-auth-token': '<x-auth-token>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    full_name: 'John Doe',
    line1: '123 Main St',
    city: 'New York',
    country: 'US',
    address_type: 'both',
    label: 'Home',
    phone: '+14155551234',
    line2: 'Apt 4B',
    state: 'NY',
    postal_code: '10001',
    is_default_shipping: false,
    is_default_billing: false
  })
};

fetch('https://api.tybritelabs.com/v1/customers/{id}/addresses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/customers/{id}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'full_name' => 'John Doe',
    'line1' => '123 Main St',
    'city' => 'New York',
    'country' => 'US',
    'address_type' => 'both',
    'label' => 'Home',
    'phone' => '+14155551234',
    'line2' => 'Apt 4B',
    'state' => 'NY',
    'postal_code' => '10001',
    'is_default_shipping' => false,
    'is_default_billing' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-auth-token: <x-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/customers/{id}/addresses"

	payload := strings.NewReader("{\n  \"full_name\": \"John Doe\",\n  \"line1\": \"123 Main St\",\n  \"city\": \"New York\",\n  \"country\": \"US\",\n  \"address_type\": \"both\",\n  \"label\": \"Home\",\n  \"phone\": \"+14155551234\",\n  \"line2\": \"Apt 4B\",\n  \"state\": \"NY\",\n  \"postal_code\": \"10001\",\n  \"is_default_shipping\": false,\n  \"is_default_billing\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-auth-token", "<x-auth-token>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/customers/{id}/addresses")
  .header("x-auth-token", "<x-auth-token>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"full_name\": \"John Doe\",\n  \"line1\": \"123 Main St\",\n  \"city\": \"New York\",\n  \"country\": \"US\",\n  \"address_type\": \"both\",\n  \"label\": \"Home\",\n  \"phone\": \"+14155551234\",\n  \"line2\": \"Apt 4B\",\n  \"state\": \"NY\",\n  \"postal_code\": \"10001\",\n  \"is_default_shipping\": false,\n  \"is_default_billing\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/customers/{id}/addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-auth-token"] = '<x-auth-token>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"full_name\": \"John Doe\",\n  \"line1\": \"123 Main St\",\n  \"city\": \"New York\",\n  \"country\": \"US\",\n  \"address_type\": \"both\",\n  \"label\": \"Home\",\n  \"phone\": \"+14155551234\",\n  \"line2\": \"Apt 4B\",\n  \"state\": \"NY\",\n  \"postal_code\": \"10001\",\n  \"is_default_shipping\": false,\n  \"is_default_billing\": false\n}"

response = http.request(request)
puts response.read_body

{
  "address": {
    "id": "c176eadf-13e3-4bdc-ba5b-06cfa3f2fcb9",
    "customer_id": "de11e44b-78e5-4940-ad54-cac237d5d30d",
    "address_type": "both",
    "label": "Home",
    "full_name": "John Doe",
    "phone": "+12125550142",
    "line1": "350 Fifth Avenue",
    "line2": "Floor 21",
    "city": "New York",
    "state": "NY",
    "postal_code": "10118",
    "country": "US",
    "is_default_shipping": true,
    "is_default_billing": true,
    "created_at": "2026-06-20T13:47:46.210663+00:00",
    "updated_at": "2026-06-20T13:47:46.210663+00:00"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
Full read/write access to all endpoints
⚠️ NEVER expose in client-side code or public repositories
Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Read-only access (GET requests only, plus POST semantic search)
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

Authentication endpoints (/v1/auth/*): Secret key required
Payment verification (POST /v1/payments/verify): Secret key required
AI Recommendations (POST /v1/recommendations): Secret key required
Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
All write operations: Secret key required
All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

x-auth-token

string

required

The signed-in shopper's session token, obtained when the shopper logs in. Must resolve to the customer in the {id} path parameter.

x-external-auth

string

Bring-your-own-auth assertion for stores that manage authentication in an external identity provider (Auth0, Clerk, Cognito, Firebase, NextAuth, SSO). Resolves the shopper whose addresses are managed.

Format: <base64url(JSON)>.<base64url(HMAC-SHA256(JSON))> where the JSON is { "external_id": "...", "iat": <unix>, "exp": <unix> } and the HMAC is keyed on the store's hmac_secret. Claim lifetime capped at 300 seconds. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.

x-idp-token

string

A raw token from the store's own identity provider (e.g. a Firebase ID token). Galactic Core forwards it to the store's configured Auth verifier, which validates it against the provider and returns the identity; resolves the shopper whose addresses are managed.

Use this when the store wants Galactic Core to verify tokens on its behalf rather than signing an assertion itself. Verification is fail-closed: if the verifier rejects the token or is unreachable, the request is unauthenticated (401). Requires an Auth verifier to be configured for the store. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.

Path Parameters

string<uuid>

required

The shopper's customer id.

Body

application/json

full_name

string

required

Example:

"John Doe"

line1

string

required

Example:

"123 Main St"

city

string

required

Example:

"New York"

country

string

required

Example:

"US"

address_type

enum<string>

default:both

Whether this address is usable for shipping, billing, or both.

Available options:

shipping,

billing,

both

label

string

An optional friendly name, e.g. "Home" or "Office".

Example:

"Home"

phone

string

Example:

"+14155551234"

line2

string

Example:

"Apt 4B"

state

string

Example:

"NY"

postal_code

string

Example:

"10001"

is_default_shipping

boolean

default:false

Set as the default address pre-selected for shipping at checkout.

is_default_billing

boolean

default:false

Set as the default address pre-selected for billing at checkout.

Response

The saved address.

address

object

required

A saved address in a shopper's personal address book. Shoppers can store multiple billing and shipping addresses and reuse them at checkout.

Show child attributes

Save a new address

curl --request POST \
  --url https://api.tybritelabs.com/v1/customers/{id}/addresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <x-auth-token>' \
  --data '
{
  "full_name": "John Doe",
  "line1": "123 Main St",
  "city": "New York",
  "country": "US",
  "address_type": "both",
  "label": "Home",
  "phone": "+14155551234",
  "line2": "Apt 4B",
  "state": "NY",
  "postal_code": "10001",
  "is_default_shipping": false,
  "is_default_billing": false
}
'

import requests

url = "https://api.tybritelabs.com/v1/customers/{id}/addresses"

payload = {
    "full_name": "John Doe",
    "line1": "123 Main St",
    "city": "New York",
    "country": "US",
    "address_type": "both",
    "label": "Home",
    "phone": "+14155551234",
    "line2": "Apt 4B",
    "state": "NY",
    "postal_code": "10001",
    "is_default_shipping": False,
    "is_default_billing": False
}
headers = {
    "x-auth-token": "<x-auth-token>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-auth-token': '<x-auth-token>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    full_name: 'John Doe',
    line1: '123 Main St',
    city: 'New York',
    country: 'US',
    address_type: 'both',
    label: 'Home',
    phone: '+14155551234',
    line2: 'Apt 4B',
    state: 'NY',
    postal_code: '10001',
    is_default_shipping: false,
    is_default_billing: false
  })
};

fetch('https://api.tybritelabs.com/v1/customers/{id}/addresses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/customers/{id}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'full_name' => 'John Doe',
    'line1' => '123 Main St',
    'city' => 'New York',
    'country' => 'US',
    'address_type' => 'both',
    'label' => 'Home',
    'phone' => '+14155551234',
    'line2' => 'Apt 4B',
    'state' => 'NY',
    'postal_code' => '10001',
    'is_default_shipping' => false,
    'is_default_billing' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-auth-token: <x-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/customers/{id}/addresses"

	payload := strings.NewReader("{\n  \"full_name\": \"John Doe\",\n  \"line1\": \"123 Main St\",\n  \"city\": \"New York\",\n  \"country\": \"US\",\n  \"address_type\": \"both\",\n  \"label\": \"Home\",\n  \"phone\": \"+14155551234\",\n  \"line2\": \"Apt 4B\",\n  \"state\": \"NY\",\n  \"postal_code\": \"10001\",\n  \"is_default_shipping\": false,\n  \"is_default_billing\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-auth-token", "<x-auth-token>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/customers/{id}/addresses")
  .header("x-auth-token", "<x-auth-token>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"full_name\": \"John Doe\",\n  \"line1\": \"123 Main St\",\n  \"city\": \"New York\",\n  \"country\": \"US\",\n  \"address_type\": \"both\",\n  \"label\": \"Home\",\n  \"phone\": \"+14155551234\",\n  \"line2\": \"Apt 4B\",\n  \"state\": \"NY\",\n  \"postal_code\": \"10001\",\n  \"is_default_shipping\": false,\n  \"is_default_billing\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/customers/{id}/addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-auth-token"] = '<x-auth-token>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"full_name\": \"John Doe\",\n  \"line1\": \"123 Main St\",\n  \"city\": \"New York\",\n  \"country\": \"US\",\n  \"address_type\": \"both\",\n  \"label\": \"Home\",\n  \"phone\": \"+14155551234\",\n  \"line2\": \"Apt 4B\",\n  \"state\": \"NY\",\n  \"postal_code\": \"10001\",\n  \"is_default_shipping\": false,\n  \"is_default_billing\": false\n}"

response = http.request(request)
puts response.read_body

{
  "address": {
    "id": "c176eadf-13e3-4bdc-ba5b-06cfa3f2fcb9",
    "customer_id": "de11e44b-78e5-4940-ad54-cac237d5d30d",
    "address_type": "both",
    "label": "Home",
    "full_name": "John Doe",
    "phone": "+12125550142",
    "line1": "350 Fifth Avenue",
    "line2": "Floor 21",
    "city": "New York",
    "state": "NY",
    "postal_code": "10118",
    "country": "US",
    "is_default_shipping": true,
    "is_default_billing": true,
    "created_at": "2026-06-20T13:47:46.210663+00:00",
    "updated_at": "2026-06-20T13:47:46.210663+00:00"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Save a new address

Authorizations

Headers

Path Parameters

Body

Response