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