Skip to main content
POST
https://api.firmly.work
/
api
/
v1
/
domains
/
{domain}
/
cart
/
shipping-info
curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "(555) 123-4567",
    "address1": "123 Main St",
    "city": "Seattle",
    "postal_code": "98101",
    "state_or_province": "Washington",
    "country": "United States"
  }'

{
  "cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
  "platform_id": "example",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "line_items": [
    {
      "line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
      "sku": "WS12-XS-Orange",
      "quantity": 1,
      "description": "Radiant Tee - Orange XS",
      "price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "requires_shipping": true
    }
  ],
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "(555) 123-4567",
    "address1": "123 Main St",
    "city": "Seattle",
    "postal_code": "98101",
    "state_or_province": "Washington",
    "country": "United States"
  },
  "shipping_method": {
    "sku": "standard_ground",
    "description": "Standard Ground (5-7 business days)",
    "price": {
      "currency": "USD",
      "value": 0,
      "symbol": "$",
      "number": 0
    }
  },
  "shipping_method_options": [
    {
      "sku": "standard_ground",
      "description": "Standard Ground (5-7 business days)",
      "price": {
        "currency": "USD",
        "value": 0,
        "symbol": "$",
        "number": 0
      },
      "estimated_days": 7
    },
    {
      "sku": "express_2day",
      "description": "Express 2-Day",
      "price": {
        "currency": "USD",
        "value": 19.99,
        "symbol": "$",
        "number": 1999
      },
      "estimated_days": 2
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 869.99,
    "symbol": "$",
    "number": 86999
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "symbol": "$",
    "number": 0
  },
  "tax": {
    "currency": "USD",
    "value": 2.20,
    "symbol": "$",
    "number": 220
  },
  "total": {
    "currency": "USD",
    "value": 24.20,
    "symbol": "$",
    "number": 2420
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    }
  ]
}

​
Overview

Sets the shipping address for the cart and automatically retrieves available shipping methods. If no shipping method was previously selected, the lowest cost option is automatically selected.

​
Authentication

​
x-firmly-authorization
string
required
Device authentication token from browser session

​
Path Parameters

​
domain
string
required
Merchant domain (e.g., staging.luma.gift)

​
Request Body

​
first_name
string
required
Customer’s first name
​
last_name
string
required
Customer’s last name
​
email
string
required
Customer’s email address
​
phone
string
Customer’s phone number (required by some merchants)
​
address1
string
required
Street address line 1
​
address2
string
Street address line 2 (apartment, suite, etc.)
​
city
string
required
Shipping city
​
postal_code
string
required
Postal/ZIP code
​
state_or_province
string
required
State or province
​
country
string
required
Country name (e.g., “United States”)

​
Response

Returns the cart with shipping information and available shipping methods.

​
Response Fields

Same as Get Cart response, plus:
​
shipping_info
object
The shipping address that was set
​
shipping_method
object
The selected shipping method (auto-selected if none was previously set)
​
shipping_method_options
array
Available shipping methods for the given address
curl --request POST \
  --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "(555) 123-4567",
    "address1": "123 Main St",
    "city": "Seattle",
    "postal_code": "98101",
    "state_or_province": "Washington",
    "country": "United States"
  }'

{
  "cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
  "platform_id": "example",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "line_items": [
    {
      "line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
      "sku": "WS12-XS-Orange",
      "quantity": 1,
      "description": "Radiant Tee - Orange XS",
      "price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "line_price": {
        "currency": "USD",
        "value": 22.00,
        "symbol": "$",
        "number": 2200
      },
      "requires_shipping": true
    }
  ],
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "(555) 123-4567",
    "address1": "123 Main St",
    "city": "Seattle",
    "postal_code": "98101",
    "state_or_province": "Washington",
    "country": "United States"
  },
  "shipping_method": {
    "sku": "standard_ground",
    "description": "Standard Ground (5-7 business days)",
    "price": {
      "currency": "USD",
      "value": 0,
      "symbol": "$",
      "number": 0
    }
  },
  "shipping_method_options": [
    {
      "sku": "standard_ground",
      "description": "Standard Ground (5-7 business days)",
      "price": {
        "currency": "USD",
        "value": 0,
        "symbol": "$",
        "number": 0
      },
      "estimated_days": 7
    },
    {
      "sku": "express_2day",
      "description": "Express 2-Day",
      "price": {
        "currency": "USD",
        "value": 19.99,
        "symbol": "$",
        "number": 1999
      },
      "estimated_days": 2
    }
  ],
  "sub_total": {
    "currency": "USD",
    "value": 869.99,
    "symbol": "$",
    "number": 86999
  },
  "shipping_total": {
    "currency": "USD",
    "value": 0,
    "symbol": "$",
    "number": 0
  },
  "tax": {
    "currency": "USD",
    "value": 2.20,
    "symbol": "$",
    "number": 220
  },
  "total": {
    "currency": "USD",
    "value": 24.20,
    "symbol": "$",
    "number": 2420
  },
  "payment_method_options": [
    {
      "type": "CreditCard",
      "wallet": "user"
    }
  ]
}

​
Error Responses

​
400 Bad Request

  • Missing or invalid authentication header
  • No items in cart that require shipping
  • Invalid email format
  • Invalid state for the given country

​
404 Not Found

Cart not found

​
412 Precondition Failed

Country not supported by merchant