Set Shipping Info - Firmly API

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>"
}
'

{
  "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

first_name

string

required

Customer’s first name

last_name

string

required

Customer’s last name

address1

string

required

Primary address line (street address)

address2

string

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

city

string

required

City name

state_or_province

string

required

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

postal_code

string

required

ZIP or postal code

country

string

required

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

phone

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"
  }'

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

Set Billing InfoSets customer billing information for payment processing

⌘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>"
}
'

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

​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