Skip to main content
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:
1

Set Shipping Information

Provide delivery address for each shipment requiring it
2

Review Consents

Present required and optional consent options
3

Accept Consents

Customer agrees to terms and policies
4

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:
TypeRequiredDescription
TERMS_OF_SERVICEYesAgreement to merchant’s terms
PRIVACY_POLICYYesAcknowledgment of data handling
MARKETING_EMAILNoPermission for promotional emails
MARKETING_SMSNoPermission for text messages
DATA_SHARINGNoAgreement to share data with partners
  1. 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
    }
  ]
}
  1. 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: 
{
  "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