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

# Overview

> Complete the checkout process

The Checkout API provides endpoints for preparing the cart for payment, including setting shipping information and managing customer consents.

## Overview

The Checkout API streamlines cart preparation with:

* **Shipping Information**: Set delivery addresses for shipments
* **Consent Management**: Handle privacy policies, terms of service, and marketing preferences
* **Multi-Shipment Support**: Different shipping addresses per shipment
* **Validation**: Real-time address validation

## Checkout Flow

A typical checkout process follows these steps:

<Steps>
  <Step title="Set Shipping Information">
    Provide delivery address for each shipment requiring it
  </Step>

  <Step title="Review Consents">
    Present required and optional consent options
  </Step>

  <Step title="Accept Consents">
    Customer agrees to terms and policies
  </Step>

  <Step title="Process Payment">
    Use Payment Processing endpoints to complete order
  </Step>
</Steps>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Set Shipping Info" icon="house" href="/api-reference/checkout/set-shipping-info">
    Configure delivery addresses for shipments
  </Card>

  <Card title="Set Billing Info" icon="credit-card" href="/api-reference/checkout/set-billing-info">
    Store billing address for future reference
  </Card>

  <Card title="Get Consents" icon="file" href="/api-reference/checkout/get-consents">
    Retrieve required and optional consent options
  </Card>

  <Card title="Set Consents" icon="check" href="/api-reference/checkout/set-consents">
    Submit customer consent selections
  </Card>
</CardGroup>

## Shipping Information

### Multi-Address Support

V2 allows different shipping addresses per shipment:

```json theme={null}
{
  "shipment_id": "ship_001",
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "+1-555-123-4567"
  }
}
```

### Address Validation

The API performs real-time validation:

* **Format Checking**: Ensures all required fields are present
* **Deliverability**: Verifies address can receive shipments
* **Standardization**: Returns standardized address format

## Billing Information

The Set Billing Info endpoint stores billing address information for the cart. Payment processing is handled separately through the Payment Processing endpoints.

<Note>
  Payment details and card information are never sent through the Checkout endpoints. Use the secure Payment Processing endpoints for handling sensitive payment data.
</Note>

## Consent Management

### Types of Consents

The API handles various consent types:

| Type               | Required | Description                           |
| ------------------ | -------- | ------------------------------------- |
| `TERMS_OF_SERVICE` | Yes      | Agreement to merchant's terms         |
| `PRIVACY_POLICY`   | Yes      | Acknowledgment of data handling       |
| `MARKETING_EMAIL`  | No       | Permission for promotional emails     |
| `MARKETING_SMS`    | No       | Permission for text messages          |
| `DATA_SHARING`     | No       | Agreement to share data with partners |

### Consent Flow Example

1. **Get Available Consents**

```bash theme={null}
GET /api/v2/domains/staging.luma.gift/checkout/consents
```

Response:

```json theme={null}
{
  "required_consents": [
    {
      "id": "terms_of_service",
      "type": "TERMS_OF_SERVICE",
      "text": "I agree to the Terms of Service",
      "url": "https://staging.luma.gift/terms"
    },
    {
      "id": "privacy_policy",
      "type": "PRIVACY_POLICY",
      "text": "I acknowledge the Privacy Policy",
      "url": "https://staging.luma.gift/privacy"
    }
  ],
  "optional_consents": [
    {
      "id": "marketing_email",
      "type": "MARKETING_EMAIL",
      "text": "Send me promotional emails",
      "default": false
    }
  ]
}
```

2. **Submit Consent Selections**

```bash theme={null}
POST /api/v2/domains/staging.luma.gift/checkout/consents
```

```json theme={null}
{
  "consents": [
    {
      "consent_id": "terms_of_service",
      "accepted": true,
      "timestamp": "2024-03-15T10:30:00Z"
    },
    {
      "consent_id": "privacy_policy",
      "accepted": true,
      "timestamp": "2024-03-15T10:30:00Z"
    },
    {
      "consent_id": "marketing_email",
      "accepted": false,
      "timestamp": "2024-03-15T10:30:00Z"
    }
  ]
}
```

## Complete Checkout Example

Here's a full checkout flow:

```javascript theme={null}
// 1. Set shipping for each shipment
for (const shipment of cart.shipments) {
  if (shipment.fulfillment_type.id === 'SHIP_TO_ADDRESS') {
    await setShippingInfo({
      shipment_id: shipment.shipment_id,
      shipping_address: customerAddress
    });
  }
}

// 2. Set billing address (optional)
await setBillingInfo({
  billing_address: billingAddress
});

// 3. Get and display consents
const consents = await getConsents();
// Show consents to customer...

// 4. Submit consent selections
await setConsents({
  consents: customerSelections
});

// 5. Process payment using Payment Processing endpoints
// See Payment Processing documentation for complete-order or place-order endpoints
```

## Validation & Error Handling

Common validation errors:

<Accordion title="Address Validation Errors">
  ```json theme={null}
  {
    "code": 400,
    "error": "InvalidAddress",
    "description": "Address could not be validated"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Consent Errors">
  ```json theme={null}
  {
    "code": 400,
    "error": "RequiredConsentMissing",
    "description": "Required consents must be accepted"
    }
  }
  ```
</Accordion>

## Integration Considerations

<Note>
  **Checkout State Management:**

  * Shipping info is stored per shipment
  * Billing info applies to the entire order
  * All required consents must be accepted
  * Validate data before submission to avoid errors
</Note>

## Next Steps

After checkout completion:

<Card title="Payment Processing" icon="credit-card" href="/api-reference/payment/get-public-key">
  Complete checkout with secure payment processing
</Card>