Skip to main content
POST
https://api.firmly.work
/
api
/
v2
/
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
​
email
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:
  1. Address Application: The provided address is used for all shipments
  2. Shipping Calculation: Each shipment’s shipping cost is calculated independently
  3. Tax Calculation: Taxes are recalculated based on the shipping destination
  4. 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": "[email protected]"
  }'

​
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": "[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"
}

​
Address Validation

The endpoint performs several validations:
  1. Country Support: Verifies the country is supported by the merchant
  2. State/Province: Validates state/province code for the given country
  3. Required Fields: Ensures all required fields are provided
  4. Email Format: Validates email address format
  5. Postal Code: Basic format validation for the country

​
Shipping Calculation Process

  1. Address Validation: Verify address is valid and supported
  2. Shipping Methods: Retrieve available shipping methods for the destination
  3. Cost Calculation: Calculate shipping cost for each shipment
  4. Tax Recalculation: Update taxes based on shipping destination
  5. 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 CodeDescriptionResolution
ErrorCartNotFoundCart does not existVerify cart ID and domain
ErrorNoLineItemCart is emptyAdd items before setting shipping
ErrorShippingNotNeededCart contains only digital itemsSkip shipping for digital-only carts
ErrorCountryNotSupportedCountry not supported by merchantUse supported country
ErrorInvalidStateInvalid state/province for countryVerify state code
ErrorInvalidEmailInvalid email formatProvide valid email address
ErrorInvalidShippingInfoShipping info validation failedCheck all required fields
ErrorInvalidInputBodyRequest body validation failedVerify request format
ErrorStoreUnavailableStore service unavailableRetry request
After setting shipping information, typical next steps include: