Checkout
Set Shipping Info
Sets the shipping address and gets available shipping methods
POST
/
api
/
v1
/
domains
/
{domain}
/
cart
/
shipping-info
curl --request POST \
--url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
--header 'x-firmly-authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "John",
"last_name": "Smith",
"email": "john@staging.luma.gift",
"phone": "(555) 123-4567",
"address1": "123 Main St",
"city": "Seattle",
"postal_code": "98101",
"state_or_province": "Washington",
"country": "United States"
}'
const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info', {
method: 'POST',
headers: {
'x-firmly-authorization': 'YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
first_name: "John",
last_name: "Smith",
email: "john@staging.luma.gift",
phone: "(555) 123-4567",
address1: "123 Main St",
city: "Seattle",
postal_code: "98101",
state_or_province: "Washington",
country: "United States"
})
});
const cart = await response.json();
import requests
response = requests.post(
'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info',
headers={
'x-firmly-authorization': 'YOUR_TOKEN',
'Content-Type': 'application/json'
},
json={
'first_name': 'John',
'last_name': 'Smith',
'email': 'john@staging.luma.gift',
'phone': '(555) 123-4567',
'address1': '123 Main St',
'city': 'Seattle',
'postal_code': '98101',
'state_or_province': 'Washington',
'country': 'United States'
}
)
cart = response.json()
{
"cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
"platform_id": "example",
"shop_id": "staging.luma.gift",
"display_name": "Luma Store",
"line_items": [
{
"line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
"sku": "WS12-XS-Orange",
"quantity": 1,
"description": "Radiant Tee - Orange XS",
"price": {
"currency": "USD",
"value": 22.00,
"symbol": "$",
"number": 2200
},
"line_price": {
"currency": "USD",
"value": 22.00,
"symbol": "$",
"number": 2200
},
"requires_shipping": true
}
],
"shipping_info": {
"first_name": "John",
"last_name": "Smith",
"email": "john@staging.luma.gift",
"phone": "(555) 123-4567",
"address1": "123 Main St",
"city": "Seattle",
"postal_code": "98101",
"state_or_province": "Washington",
"country": "United States"
},
"shipping_method": {
"sku": "standard_ground",
"description": "Standard Ground (5-7 business days)",
"price": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
}
},
"shipping_method_options": [
{
"sku": "standard_ground",
"description": "Standard Ground (5-7 business days)",
"price": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
},
"estimated_days": 7
},
{
"sku": "express_2day",
"description": "Express 2-Day",
"price": {
"currency": "USD",
"value": 19.99,
"symbol": "$",
"number": 1999
},
"estimated_days": 2
}
],
"sub_total": {
"currency": "USD",
"value": 869.99,
"symbol": "$",
"number": 86999
},
"shipping_total": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
},
"tax": {
"currency": "USD",
"value": 2.20,
"symbol": "$",
"number": 220
},
"total": {
"currency": "USD",
"value": 24.20,
"symbol": "$",
"number": 2420
},
"payment_method_options": [
{
"type": "CreditCard",
"wallet": "user"
}
]
}
Overview
Sets the shipping address for the cart and automatically retrieves available shipping methods. If no shipping method was previously selected, the lowest cost option is automatically selected.Authentication
string
required
Device authentication token from browser session
Path Parameters
string
required
Merchant domain (e.g.,
staging.luma.gift)Request Body
string
required
Customer’s first name
string
required
Customer’s last name
string
required
Customer’s email address
string
Customer’s phone number (required by some merchants)
string
required
Street address line 1
string
Street address line 2 (apartment, suite, etc.)
string
required
Shipping city
string
required
Postal/ZIP code
string
required
State or province
string
required
Country name (e.g., “United States”)
Response
Returns the cart with shipping information and available shipping methods.Response Fields
Same as Get Cart response, plus:object
The shipping address that was set
object
The selected shipping method (auto-selected if none was previously set)
array
curl --request POST \
--url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
--header 'x-firmly-authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "John",
"last_name": "Smith",
"email": "john@staging.luma.gift",
"phone": "(555) 123-4567",
"address1": "123 Main St",
"city": "Seattle",
"postal_code": "98101",
"state_or_province": "Washington",
"country": "United States"
}'
const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info', {
method: 'POST',
headers: {
'x-firmly-authorization': 'YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
first_name: "John",
last_name: "Smith",
email: "john@staging.luma.gift",
phone: "(555) 123-4567",
address1: "123 Main St",
city: "Seattle",
postal_code: "98101",
state_or_province: "Washington",
country: "United States"
})
});
const cart = await response.json();
import requests
response = requests.post(
'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info',
headers={
'x-firmly-authorization': 'YOUR_TOKEN',
'Content-Type': 'application/json'
},
json={
'first_name': 'John',
'last_name': 'Smith',
'email': 'john@staging.luma.gift',
'phone': '(555) 123-4567',
'address1': '123 Main St',
'city': 'Seattle',
'postal_code': '98101',
'state_or_province': 'Washington',
'country': 'United States'
}
)
cart = response.json()
{
"cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
"platform_id": "example",
"shop_id": "staging.luma.gift",
"display_name": "Luma Store",
"line_items": [
{
"line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
"sku": "WS12-XS-Orange",
"quantity": 1,
"description": "Radiant Tee - Orange XS",
"price": {
"currency": "USD",
"value": 22.00,
"symbol": "$",
"number": 2200
},
"line_price": {
"currency": "USD",
"value": 22.00,
"symbol": "$",
"number": 2200
},
"requires_shipping": true
}
],
"shipping_info": {
"first_name": "John",
"last_name": "Smith",
"email": "john@staging.luma.gift",
"phone": "(555) 123-4567",
"address1": "123 Main St",
"city": "Seattle",
"postal_code": "98101",
"state_or_province": "Washington",
"country": "United States"
},
"shipping_method": {
"sku": "standard_ground",
"description": "Standard Ground (5-7 business days)",
"price": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
}
},
"shipping_method_options": [
{
"sku": "standard_ground",
"description": "Standard Ground (5-7 business days)",
"price": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
},
"estimated_days": 7
},
{
"sku": "express_2day",
"description": "Express 2-Day",
"price": {
"currency": "USD",
"value": 19.99,
"symbol": "$",
"number": 1999
},
"estimated_days": 2
}
],
"sub_total": {
"currency": "USD",
"value": 869.99,
"symbol": "$",
"number": 86999
},
"shipping_total": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
},
"tax": {
"currency": "USD",
"value": 2.20,
"symbol": "$",
"number": 220
},
"total": {
"currency": "USD",
"value": 24.20,
"symbol": "$",
"number": 2420
},
"payment_method_options": [
{
"type": "CreditCard",
"wallet": "user"
}
]
}
Error Responses
400 Bad Request
- Missing or invalid authentication header
- No items in cart that require shipping
- Invalid email format
- Invalid state for the given country
404 Not Found
Cart not found412 Precondition Failed
Country not supported by merchant⌘I
curl --request POST \
--url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
--header 'x-firmly-authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "John",
"last_name": "Smith",
"email": "john@staging.luma.gift",
"phone": "(555) 123-4567",
"address1": "123 Main St",
"city": "Seattle",
"postal_code": "98101",
"state_or_province": "Washington",
"country": "United States"
}'
const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info', {
method: 'POST',
headers: {
'x-firmly-authorization': 'YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
first_name: "John",
last_name: "Smith",
email: "john@staging.luma.gift",
phone: "(555) 123-4567",
address1: "123 Main St",
city: "Seattle",
postal_code: "98101",
state_or_province: "Washington",
country: "United States"
})
});
const cart = await response.json();
import requests
response = requests.post(
'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info',
headers={
'x-firmly-authorization': 'YOUR_TOKEN',
'Content-Type': 'application/json'
},
json={
'first_name': 'John',
'last_name': 'Smith',
'email': 'john@staging.luma.gift',
'phone': '(555) 123-4567',
'address1': '123 Main St',
'city': 'Seattle',
'postal_code': '98101',
'state_or_province': 'Washington',
'country': 'United States'
}
)
cart = response.json()
{
"cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
"platform_id": "example",
"shop_id": "staging.luma.gift",
"display_name": "Luma Store",
"line_items": [
{
"line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
"sku": "WS12-XS-Orange",
"quantity": 1,
"description": "Radiant Tee - Orange XS",
"price": {
"currency": "USD",
"value": 22.00,
"symbol": "$",
"number": 2200
},
"line_price": {
"currency": "USD",
"value": 22.00,
"symbol": "$",
"number": 2200
},
"requires_shipping": true
}
],
"shipping_info": {
"first_name": "John",
"last_name": "Smith",
"email": "john@staging.luma.gift",
"phone": "(555) 123-4567",
"address1": "123 Main St",
"city": "Seattle",
"postal_code": "98101",
"state_or_province": "Washington",
"country": "United States"
},
"shipping_method": {
"sku": "standard_ground",
"description": "Standard Ground (5-7 business days)",
"price": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
}
},
"shipping_method_options": [
{
"sku": "standard_ground",
"description": "Standard Ground (5-7 business days)",
"price": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
},
"estimated_days": 7
},
{
"sku": "express_2day",
"description": "Express 2-Day",
"price": {
"currency": "USD",
"value": 19.99,
"symbol": "$",
"number": 1999
},
"estimated_days": 2
}
],
"sub_total": {
"currency": "USD",
"value": 869.99,
"symbol": "$",
"number": 86999
},
"shipping_total": {
"currency": "USD",
"value": 0,
"symbol": "$",
"number": 0
},
"tax": {
"currency": "USD",
"value": 2.20,
"symbol": "$",
"number": 220
},
"total": {
"currency": "USD",
"value": 24.20,
"symbol": "$",
"number": 2420
},
"payment_method_options": [
{
"type": "CreditCard",
"wallet": "user"
}
]
}