Set Billing Info

POST

api

domains

{domain}

cart

billing-info

Set Billing Info

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/billing-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/billing-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/billing-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/billing-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/billing-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/billing-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/billing-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 billing information for the cart. This endpoint is typically used when the billing address differs from the shipping address. The billing information is used for payment processing and invoice generation.

If billing address is the same as shipping address, you may skip this endpoint and the shipping address will be used for billing by default.

Request Body

string

required

Customer’s first name for billing

string

required

Customer’s last name for billing

string

required

Primary billing address line

string

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

string

required

Billing city name

string

required

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

string

required

Billing ZIP or postal code

string

required

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

string

required

Billing contact phone number

string

required

Billing contact email address

Response

Returns a complete ShoppingCart object with updated billing information. The cart totals remain unchanged as billing address doesn’t affect shipping or tax calculations.

When to Use Billing Info

Common Scenarios

Different Billing Address: Customer’s credit card billing address differs from shipping
Gift Orders: Shipping to recipient but billing to purchaser
Business Orders: Shipping to office but billing to headquarters
Digital Products: No shipping address but billing address required

Default Behavior

If this endpoint is not called:

Shipping address is used as billing address
Both addresses must match for payment processing

Code Examples

curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/billing-info \
  -H "x-firmly-authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "456 Billing Street",
    "address2": "Suite 100",
    "city": "Billing City",
    "state_or_province": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "555-987-6543",
    "email": "jane.doe@staging.luma.gift"
  }'

const billingInfo = {
  first_name: "Jane",
  last_name: "Doe",
  address1: "456 Billing Street",
  address2: "Suite 100",
  city: "Billing City",
  state_or_province: "NY",
  postal_code: "10001",
  country: "US",
  phone: "555-987-6543",
  email: "jane.doe@staging.luma.gift"
};

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

const updatedCart = await response.json();

import requests

billing_info = {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "456 Billing Street",
    "address2": "Suite 100",
    "city": "Billing City",
    "state_or_province": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "555-987-6543",
    "email": "jane.doe@staging.luma.gift"
}

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

updated_cart = response.json()

$billingInfo = [
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'address1' => '456 Billing Street',
    'address2' => 'Suite 100',
    'city' => 'Billing City',
    'state_or_province' => 'NY',
    'postal_code' => '10001',
    'country' => 'US',
    'phone' => '555-987-6543',
    'email' => 'jane.doe@example.com'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/billing-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($billingInfo));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

Response Example

{
  "line_items": [...],
  "shipments": [...],
  "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"
  },
  "billing_info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "456 Billing Street",
    "address2": "Suite 100",
    "city": "Billing City",
    "state_or_province": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "555-987-6543",
    "email": "jane.doe@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"
}

Billing Address Validation

Similar to shipping address, the billing address undergoes validation:

Country Support: Verifies billing country is supported
State/Province: Validates state/province for the country
Required Fields: Ensures all required fields are present
Email Format: Validates email address format

Billing address validation is primarily for data integrity. Payment processors may perform additional address verification (AVS) during payment processing.

Billing Address Behavior

Independent from Shipping: Billing info can be set independently of shipping
No Tax Impact: Billing address doesn’t affect tax calculations (taxes based on shipping destination)
Schema Compatibility: Uses the same address schema as shipping for consistency
Session Storage: Billing info is stored in the cart session

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
`ErrorCountryNotSupported`	Billing country not supported	Use supported country
`ErrorInvalidState`	Invalid state/province for country	Verify state code
`ErrorInvalidInputBody`	Request body validation failed	Check request format
`MissingAuthHeader`	Missing authorization header	Include x-firmly-authorization
`InvalidToken`	Invalid JWT token	Refresh authentication token

Checkout Flow Integration

The typical checkout flow sequence:

Add Items to Cart - Build the cart
Set Shipping Info - Add shipping address
Set Billing Info - Add billing address (this endpoint)
Set Consents - Handle consent management
Complete Order - Complete the purchase

⌘I

Set Billing Info

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/billing-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/billing-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/billing-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/billing-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/billing-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/billing-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/billing-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

When to Use Billing Info

Common Scenarios

Default Behavior

Code Examples

Response Example

Billing Address Validation

Billing Address Behavior

Error Responses

Common Errors

Checkout Flow Integration

​Overview

​Request Body

​Response

​When to Use Billing Info

​Common Scenarios

​Default Behavior

​Code Examples

​Response Example

​Billing Address Validation

​Billing Address Behavior

​Error Responses

​Common Errors

​Checkout Flow Integration

Overview

Request Body

Response

When to Use Billing Info

Common Scenarios

Default Behavior

Code Examples

Response Example

Billing Address Validation

Billing Address Behavior

Error Responses

Common Errors

Checkout Flow Integration