Overview

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

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:

Set Shipping Information

Provide delivery address for each shipment requiring it

Review Consents

Present required and optional consent options

Accept Consents

Customer agrees to terms and policies

Process Payment

Use Payment Processing endpoints to complete order

Available Endpoints

Set Shipping Info

Configure delivery addresses for shipments

Set Billing Info

Store billing address for future reference

Get Consents

Retrieve required and optional consent options

Set Consents

Submit customer consent selections

Shipping Information

Multi-Address Support

V2 allows different shipping addresses per shipment:

{
  "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.

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

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

Get Available Consents

GET /api/v2/domains/staging.luma.gift/checkout/consents

Response:

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

Submit Consent Selections

POST /api/v2/domains/staging.luma.gift/checkout/consents

{
  "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:

// 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:

Address Validation Errors

{
  "code": 400,
  "error": "InvalidAddress",
  "description": "Address could not be validated"
    }
  }
}

Integration Considerations

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

Next Steps

After checkout completion:

Payment Processing

Complete checkout with secure payment processing

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Overview

Checkout Flow

Available Endpoints

Set Shipping Info

Set Billing Info

Get Consents

Set Consents

Shipping Information

Multi-Address Support

Address Validation

Billing Information

Types of Consents

Complete Checkout Example

Validation & Error Handling

Integration Considerations

Next Steps

Payment Processing

​Overview

​Checkout Flow

​Available Endpoints

Set Shipping Info

Set Billing Info

Get Consents

Set Consents

​Shipping Information

​Multi-Address Support

​Address Validation

​Billing Information

​Consent Management

​Types of Consents

​Consent Flow Example

​Complete Checkout Example

​Validation & Error Handling

​Integration Considerations

​Next Steps

Payment Processing

Overview

Checkout Flow

Available Endpoints

Shipping Information

Multi-Address Support

Address Validation

Billing Information

Consent Management

Types of Consents

Consent Flow Example

Complete Checkout Example

Validation & Error Handling

Integration Considerations

Next Steps