> ## 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 customer shipping information and calculate shipping costs

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

<Note>
  Both `POST` and `PUT` methods are supported for this endpoint, providing flexibility for different client implementations.
</Note>

## 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="address1" type="string" required>
  Primary address line (street address)
</ParamField>

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

<ParamField body="city" type="string" required>
  City name
</ParamField>

<ParamField body="state_or_province" type="string" required>
  State or province code (e.g., "CA", "NY") or full name
</ParamField>

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

<ParamField body="country" type="string" required>
  Country code in ISO 3166-1 alpha-2 format (e.g., "US", "CA")
</ParamField>

<ParamField body="phone" type="string" required>
  Contact phone number for delivery
</ParamField>

<ParamField body="email" type="string" required>
  Contact email address
</ParamField>

## Response

Returns a complete [ShoppingCart](/api-reference/cart-management/get-cart) 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const shippingInfo = {
    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"
  };

  const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(shippingInfo)
  });

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

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

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

  response = requests.post(
      'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info',
      headers={
          'x-firmly-authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json=shipping_info
  )

  updated_cart = response.json()
  ```

  ```php PHP theme={null}
  $shippingInfo = [
      '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@example.com'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipping-info');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-firmly-authorization: Bearer YOUR_TOKEN',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($shippingInfo));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $updatedCart = json_decode($response, true);
  curl_close($ch);
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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:

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

<ResponseExample>
  ```json theme={null}
  {
    "code": 400,
    "error": "ErrorCountryNotSupported",
    "description": "Country 'XX' is not supported by this merchant"
  }
  ```
</ResponseExample>

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

## Related Operations

After setting shipping information, typical next steps include:

* [Set Billing Info](/api-reference/checkout/set-billing-info) - Add billing address
* [Set Consents](/api-reference/checkout/set-consents) - Update consent preferences
* [Complete Order](/api-reference/payment/complete-order-v2) - Complete the purchase