Set Shipping Info

POST

api

domains

{domain}

cart

shipping-info

Set Shipping Info

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "address1": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state_or_province": "<string>",
  "postal_code": "<string>",
  "country": "<string>",
  "phone": "<string>",
  "email": "<string>"
}
'

import requests

url = "https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info"

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state_or_province": "<string>",
    "postal_code": "<string>",
    "country": "<string>",
    "phone": "<string>",
    "email": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: '<string>',
    last_name: '<string>',
    address1: '<string>',
    address2: '<string>',
    city: '<string>',
    state_or_province: '<string>',
    postal_code: '<string>',
    country: '<string>',
    phone: '<string>',
    email: '<string>'
  })
};

fetch('https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info', 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.firmly.work/api/v2/domains/{domain}/cart/shipping-info",
  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([
    'first_name' => '<string>',
    'last_name' => '<string>',
    'address1' => '<string>',
    'address2' => '<string>',
    'city' => '<string>',
    'state_or_province' => '<string>',
    'postal_code' => '<string>',
    'country' => '<string>',
    'phone' => '<string>',
    'email' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.firmly.work/api/v2/domains/{domain}/cart/shipping-info"

	payload := strings.NewReader("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"address1\": \"<string>\",\n  \"address2\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state_or_province\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"country\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\"\n}")

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

	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.firmly.work/api/v2/domains/{domain}/cart/shipping-info")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"address1\": \"<string>\",\n  \"address2\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state_or_province\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"country\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"address1\": \"<string>\",\n  \"address2\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state_or_province\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"country\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\"\n}"

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

{
  "code": 400,
  "error": "ErrorCountryNotSupported",
  "description": "Country 'XX' is not supported by this merchant"
}

Overview

Sets customer shipping information for cart delivery. This endpoint validates the address, calculates shipping costs based on available shipping methods, and updates cart totals. This endpoint supports multi-shipment scenarios where different items may ship from different locations.

Both POST and PUT methods are supported for this endpoint, providing flexibility for different client implementations.

Request Body

string

required

Customer’s first name

string

required

Customer’s last name

string

required

Primary address line (street address)

string

Secondary address line (apartment, suite, unit, etc.)

string

required

City name

string

required

State or province code (e.g., “CA”, “NY”) or full name

string

required

ZIP or postal code

string

required

Country code in ISO 3166-1 alpha-2 format (e.g., “US”, “CA”)

string

required

Contact phone number for delivery

string

required

Contact email address

Response

Returns a complete ShoppingCart object with:

Updated shipping information
Calculated shipping costs per shipment
Updated tax calculations based on shipping address
Recalculated cart totals

Multi-Shipment Behavior

The shipping address applies to all shipments in the cart. Key behaviors:

Address Application: The provided address is used for all shipments
Shipping Calculation: Each shipment’s shipping cost is calculated independently
Tax Calculation: Taxes are recalculated based on the shipping destination
Validation: Address is validated against merchant’s supported regions

Code Examples

curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info \
  -H "x-firmly-authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "Anytown",
    "state_or_province": "CA",
    "postal_code": "12345",
    "country": "US",
    "phone": "555-123-4567",
    "email": "john.smith@staging.luma.gift"
  }'

const shippingInfo = {
  first_name: "John",
  last_name: "Smith",
  address1: "123 Main Street",
  address2: "Apt 4B",
  city: "Anytown",
  state_or_province: "CA",
  postal_code: "12345",
  country: "US",
  phone: "555-123-4567",
  email: "john.smith@staging.luma.gift"
};

const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(shippingInfo)
});

const updatedCart = await response.json();

import requests

shipping_info = {
    "first_name": "John",
    "last_name": "Smith",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "Anytown",
    "state_or_province": "CA",
    "postal_code": "12345",
    "country": "US",
    "phone": "555-123-4567",
    "email": "john.smith@staging.luma.gift"
}

response = requests.post(
    'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info',
    headers={
        'x-firmly-authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json=shipping_info
)

updated_cart = response.json()

$shippingInfo = [
    'first_name' => 'John',
    'last_name' => 'Smith',
    'address1' => '123 Main Street',
    'address2' => 'Apt 4B',
    'city' => 'Anytown',
    'state_or_province' => 'CA',
    'postal_code' => '12345',
    'country' => 'US',
    'phone' => '555-123-4567',
    'email' => 'john.smith@example.com'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-firmly-authorization: Bearer YOUR_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($shippingInfo));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$updatedCart = json_decode($response, true);
curl_close($ch);

Response Example

{
  "line_items": [
    {
      "line_item_id": "item-ws12-orange-1",
      "sku": "WS12-XS-Orange",
      "description": "Radiant Tee",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-12345",
      "line_item_ids": ["item-ws12-orange-1"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "shipping_method": {
        "id": "STANDARD_GROUND",
        "description": "Standard Ground (5-7 business days)",
        "price": {
          "currency": "USD",
          "value": 9.99,
          "number": 999,
          "symbol": "$"
        },
        "estimated_delivery": "5-7 business days"
      }
    }
  ],
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "Anytown",
    "state_or_province": "CA",
    "postal_code": "12345",
    "country": "US",
    "phone": "555-123-4567",
    "email": "john.smith@staging.luma.gift"
  },
  "sub_total": {
    "currency": "USD",
    "value": 44.00,
    "number": 4400,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 9.99,
    "number": 999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 4.40,
    "number": 440,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 58.39,
    "number": 5839,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

Address Validation

The endpoint performs several validations:

Country Support: Verifies the country is supported by the merchant
State/Province: Validates state/province code for the given country
Required Fields: Ensures all required fields are provided
Email Format: Validates email address format
Postal Code: Basic format validation for the country

Shipping Calculation Process

Address Validation: Verify address is valid and supported
Shipping Methods: Retrieve available shipping methods for the destination
Cost Calculation: Calculate shipping cost for each shipment
Tax Recalculation: Update taxes based on shipping destination
Total Update: Recalculate cart totals with shipping and tax

Error Responses

{
  "code": 400,
  "error": "ErrorCountryNotSupported",
  "description": "Country 'XX' is not supported by this merchant"
}

Common Errors

Error Code	Description	Resolution
`ErrorCartNotFound`	Cart does not exist	Verify cart ID and domain
`ErrorNoLineItem`	Cart is empty	Add items before setting shipping
`ErrorShippingNotNeeded`	Cart contains only digital items	Skip shipping for digital-only carts
`ErrorCountryNotSupported`	Country not supported by merchant	Use supported country
`ErrorInvalidState`	Invalid state/province for country	Verify state code
`ErrorInvalidEmail`	Invalid email format	Provide valid email address
`ErrorInvalidShippingInfo`	Shipping info validation failed	Check all required fields
`ErrorInvalidInputBody`	Request body validation failed	Verify request format
`ErrorStoreUnavailable`	Store service unavailable	Retry request

After setting shipping information, typical next steps include:

Set Billing Info - Add billing address
Set Consents - Update consent preferences
Complete Order - Complete the purchase

⌘I

Set Shipping Info

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "address1": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state_or_province": "<string>",
  "postal_code": "<string>",
  "country": "<string>",
  "phone": "<string>",
  "email": "<string>"
}
'

import requests

url = "https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info"

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state_or_province": "<string>",
    "postal_code": "<string>",
    "country": "<string>",
    "phone": "<string>",
    "email": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: '<string>',
    last_name: '<string>',
    address1: '<string>',
    address2: '<string>',
    city: '<string>',
    state_or_province: '<string>',
    postal_code: '<string>',
    country: '<string>',
    phone: '<string>',
    email: '<string>'
  })
};

fetch('https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info', 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.firmly.work/api/v2/domains/{domain}/cart/shipping-info",
  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([
    'first_name' => '<string>',
    'last_name' => '<string>',
    'address1' => '<string>',
    'address2' => '<string>',
    'city' => '<string>',
    'state_or_province' => '<string>',
    'postal_code' => '<string>',
    'country' => '<string>',
    'phone' => '<string>',
    'email' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.firmly.work/api/v2/domains/{domain}/cart/shipping-info"

	payload := strings.NewReader("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"address1\": \"<string>\",\n  \"address2\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state_or_province\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"country\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\"\n}")

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

	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.firmly.work/api/v2/domains/{domain}/cart/shipping-info")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"address1\": \"<string>\",\n  \"address2\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state_or_province\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"country\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v2/domains/{domain}/cart/shipping-info")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"address1\": \"<string>\",\n  \"address2\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state_or_province\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"country\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"email\": \"<string>\"\n}"

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

{
  "code": 400,
  "error": "ErrorCountryNotSupported",
  "description": "Country 'XX' is not supported by this merchant"
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Request Body

Response

Multi-Shipment Behavior

Code Examples

Response Example

Address Validation

Shipping Calculation Process

Error Responses

Common Errors

​Overview

​Request Body

​Response

​Multi-Shipment Behavior

​Code Examples

​Response Example

​Address Validation

​Shipping Calculation Process

​Error Responses

​Common Errors

​Related Operations

Overview

Request Body

Response

Multi-Shipment Behavior

Code Examples

Response Example

Address Validation

Shipping Calculation Process

Error Responses

Common Errors

Related Operations