Orders

The order flow consists of two steps: validate then place. This two-step process ensures accurate pricing and catches issues before charging the customer.

Order Flow Overview

1. Validate - Submit cart and fulfillment details, receive pricing and any errors
2. Place - If valid, submit payment and complete the order

Validate Order

Why Validate First?

The validate step is essential because:

• Pricing accuracy - Get final total including taxes, fees, and promotions
• Availability check - Items may become unavailable between browsing and checkout
• Store status - Store may have closed or stopped accepting orders
• Modifier validation - Catch missing required modifiers or exceeded limits
• Delivery validation - Verify address is within delivery range

Request Body

POST /order/validate

{
  "cart": {
    "storeId": "store_123",
    "catalogSetId": "catalog_456",
    "lineItems": [
      {
        "lineItemId": "li_001",
        "itemId": "item_pizza",
        "quantity": 2,
        "modifierGroups": [
          {
            "modifierGroupId": "mod_size",
            "selectedModifiers": [
              { "itemId": "size_large", "quantity": 1 }
            ]
          }
        ]
      }
    ]
  },
  "fulfillment": {
    "type": "delivery",
    "deliveryAddress": {
      "address": "123 Main St, New York, NY 10001",
      "unit": "Apt 4B",
      "instructions": "Ring buzzer 4B"
    }
  },
  "tip": 5.00
}

Successful Response

{
  "validatedOrderToken": "tok_abc123...",
  "isValid": true,
  "amounts": {
    "subtotal": 45.98,
    "tax": 4.08,
    "deliveryFee": 3.99,
    "serviceFee": 2.50,
    "tip": 5.00,
    "total": 61.55
  },
  "estimatedReadyTime": "35-45 min",
  "errors": []
}

Validation Errors

When isValid is false, the errors array contains issues to address:

{
  "validatedOrderToken": null,
  "isValid": false,
  "errors": [
    {
      "code": "ITEM_UNAVAILABLE",
      "message": "Margherita Pizza is currently unavailable",
      "itemId": "item_pizza"
    }
  ]
}

Code	Description	How to Handle
CART_EMPTY	Cart has no items	Show "Your cart is empty"
ITEM_UNAVAILABLE	Item no longer available	Remove item, suggest alternatives
ITEM_PRICE_CHANGED	Price has changed	Show updated price, ask to confirm
MODIFIER_UNAVAILABLE	Selected modifier unavailable	Remove modifier, show alternatives
MODIFIER_REQUIRED	Required modifier not selected	Prompt user to complete selection
MINIMUM_ORDER_NOT_MET	Below delivery minimum	Show minimum and current total
STORE_CLOSED	Store is closed	Show hours, suggest other stores
STORE_NOT_ACCEPTING_ORDERS	Store temporarily offline	Suggest trying later
DELIVERY_ADDRESS_OUT_OF_RANGE	Address outside delivery area	Suggest pickup or other stores
INVALID_ADDRESS	Address couldn't be validated	Ask user to verify address

Place Order

Once you have a validatedOrderToken, you can place the order.

Token Expiration

The validatedOrderToken expires after 15 minutes. If expired, call validate again.

Request Body

POST /order/place

{
  "validatedOrderToken": "tok_abc123...",
  "payment": {
    "type": "card_on_file",
    "paymentToken": "pm_abc123"
  },
  "customerInfo": {
    "email": "customer@example.com",
    "phone": "+1-555-123-4567",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Card-on-File Payment

For Card-on-File integrations, the payment object requires only two fields:

Field	Type	Description
type	string	Must be "card_on_file"
paymentToken	string	Your platform's reference to the saved payment method

The paymentToken should match a payment method passed during session creation (SDK integrations) or a payment reference configured with Gett (API integrations).

Card-on-File Setup Required

Card-on-File interchange must be configured for your integration before use. See the Payments Guide for setup information.

Payment Options

See the Payments Guide for details on payment types and Card-on-File setup.

Successful Response

{
  "orderId": "ord_789xyz",
  "status": "RECEIVED",
  "store": {
    "storeId": "store_123",
    "name": "Pizza Palace",
    "phone": "+1-555-987-6543"
  },
  "amounts": {
    "subtotal": 45.98,
    "tax": 4.08,
    "deliveryFee": 3.99,
    "serviceFee": 2.50,
    "tip": 5.00,
    "total": 61.55
  },
  "estimatedReadyTime": "2024-01-15T19:30:00Z",
  "placedAt": "2024-01-15T18:55:00Z"
}

Order Statuses

Status	Description
PENDING	Order submitted, awaiting store confirmation
RECEIVED	Store received the order
CONFIRMED	Store confirmed and is preparing
PREPARING	Order is being made
READY	Ready for pickup/handoff to driver
OUT_FOR_DELIVERY	Driver has the order (delivery only)
DELIVERED	Order delivered to customer
COMPLETED	Order complete
CANCELLED	Order was cancelled

Placement Errors

Error	Description	How to Handle
TOKEN_EXPIRED	Validation token expired	Call validate again
TOKEN_ALREADY_USED	Token was already used	Show duplicate order warning
PAYMENT_FAILED	Payment processing error	Ask to retry or use different payment
PAYMENT_DECLINED	Card was declined	Ask for different payment method
PAYMENT_METHOD_NOT_FOUND	The paymentToken is not recognized	Verify paymentToken was in session (SDK) or configured (API)
PAYMENT_RETRIEVAL_FAILED	Unable to retrieve payment data	Contact Gett support
PAYMENT_METHOD_EXPIRED	The card has expired	User should update payment on your platform
PAYMENT_INTERCHANGE_NOT_CONFIGURED	Card-on-File not enabled	Contact your Gett representative
STORE_REJECTED	Store couldn't fulfill order	Contact support or try another store

API Reference

• Validate Order - Full request/response schema
• Place Order - Full request/response schema

Related

• Stores - Finding stores for ordering
• CatalogSets - Menu structure and item details
• Cart Helpers - Building the cart
• Payments - Payment options and Card-on-File setup