> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Shipping Info

> Sets the shipping address and gets available shipping methods

## 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

<Card>
  <ParamField header="x-firmly-authorization" type="string" required>
    Device authentication token from browser session
  </ParamField>
</Card>

## Path Parameters

<ParamField path="domain" type="string" required>
  Merchant domain (e.g., `staging.luma.gift`)
</ParamField>

## Request Body

<ParamField body="first_name" type="string" required>
  Customer's first name
</ParamField>

<ParamField body="last_name" type="string" required>
  Customer's last name
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address
</ParamField>

<ParamField body="phone" type="string">
  Customer's phone number (required by some merchants)
</ParamField>

<ParamField body="address1" type="string" required>
  Street address line 1
</ParamField>

<ParamField body="address2" type="string">
  Street address line 2 (apartment, suite, etc.)
</ParamField>

<ParamField body="city" type="string" required>
  Shipping city
</ParamField>

<ParamField body="postal_code" type="string" required>
  Postal/ZIP code
</ParamField>

<ParamField body="state_or_province" type="string" required>
  State or province
</ParamField>

<ParamField body="country" type="string" required>
  Country name (e.g., "United States")
</ParamField>

## Response

Returns the cart with shipping information and available shipping methods.

### Response Fields

Same as [Get Cart](/api-reference/simple-cart-api/cart/get-cart#response-fields) response, plus:

<ResponseField name="shipping_info" type="object">
  The shipping address that was set
</ResponseField>

<ResponseField name="shipping_method" type="object">
  The selected shipping method (auto-selected if none was previously set)
</ResponseField>

<ResponseField name="shipping_method_options" type="array">
  Available shipping methods for the given address

  <Expandable title="Shipping Method Object">
    <ResponseField name="sku" type="string">
      Shipping method identifier
    </ResponseField>

    <ResponseField name="description" type="string">
      Shipping method description
    </ResponseField>

    <ResponseField name="price" type="object">
      Shipping cost
    </ResponseField>

    <ResponseField name="estimated_days" type="number">
      Estimated delivery days
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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": "john@staging.luma.gift",
      "phone": "(555) 123-4567",
      "address1": "123 Main St",
      "city": "Seattle",
      "postal_code": "98101",
      "state_or_province": "Washington",
      "country": "United States"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': 'YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: "John",
      last_name: "Smith",
      email: "john@staging.luma.gift",
      phone: "(555) 123-4567",
      address1: "123 Main St",
      city: "Seattle",
      postal_code: "98101",
      state_or_province: "Washington",
      country: "United States"
    })
  });

  const cart = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/shipping-info',
      headers={
          'x-firmly-authorization': 'YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'first_name': 'John',
          'last_name': 'Smith',
          'email': 'john@staging.luma.gift',
          'phone': '(555) 123-4567',
          'address1': '123 Main St',
          'city': 'Seattle',
          'postal_code': '98101',
          'state_or_province': 'Washington',
          'country': 'United States'
      }
  )

  cart = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "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": "john@staging.luma.gift",
      "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"
      }
    ]
  }
  ```
</ResponseExample>

## 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