Skip to main content
POST
https://api.firmly.work
/
api
/
v2
/
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>"
}
'
{
  "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

​
first_name
string
required
Customer’s first name for billing
​
last_name
string
required
Customer’s last name for billing
​
address1
string
required
Primary billing address line
​
address2
string
Secondary billing address line (apartment, suite, etc.)
​
city
string
required
Billing city name
​
state_or_province
string
required
Billing state or province code (e.g., “CA”, “NY”) or full name
​
postal_code
string
required
Billing ZIP or postal code
​
country
string
required
Billing country code in ISO 3166-1 alpha-2 format (e.g., “US”, “CA”)
​
phone
string
required
Billing contact phone number
​
email
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

  1. Different Billing Address: Customer’s credit card billing address differs from shipping
  2. Gift Orders: Shipping to recipient but billing to purchaser
  3. Business Orders: Shipping to office but billing to headquarters
  4. 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": "[email protected]"
  }'

​
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": "[email protected]"
  },
  "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": "[email protected]"
  },
  "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:
  1. Country Support: Verifies billing country is supported
  2. State/Province: Validates state/province for the country
  3. Required Fields: Ensures all required fields are present
  4. 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

  1. Independent from Shipping: Billing info can be set independently of shipping
  2. No Tax Impact: Billing address doesn’t affect tax calculations (taxes based on shipping destination)
  3. Schema Compatibility: Uses the same address schema as shipping for consistency
  4. 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 CodeDescriptionResolution
ErrorCartNotFoundCart does not existVerify cart ID and domain
ErrorCountryNotSupportedBilling country not supportedUse supported country
ErrorInvalidStateInvalid state/province for countryVerify state code
ErrorInvalidInputBodyRequest body validation failedCheck request format
MissingAuthHeaderMissing authorization headerInclude x-firmly-authorization
InvalidTokenInvalid JWT tokenRefresh authentication token

​
Checkout Flow Integration

The typical checkout flow sequence:
  1. Add Items to Cart - Build the cart
  2. Set Shipping Info - Add shipping address
  3. Set Billing Info - Add billing address (this endpoint)
  4. Set Consents - Handle consent management
  5. Complete Order - Complete the purchase