Order Tracking

After a customer completes checkout, keep them informed with order status updates. This guide covers how to poll for status changes and display progress in your storefront.

Order status flow

Orders progress through these statuses:

OPEN → LOCKED → COMPLETED

Status	Meaning
`OPEN`	Cart is active — items can be added or modified
`LOCKED`	Payment is being processed — cart is frozen
`COMPLETED`	Payment confirmed — order sent to the restaurant

Poll for status updates

After the customer completes payment, poll the cart endpoint to check for status changes.

import { storefront } from '@/lib/storefront';

async function pollOrderStatus(locationId: string, cartId: string) {
  const poll = setInterval(async () => {
    const cart = await storefront.cart.get(locationId, cartId);

    if (cart.status === 'COMPLETED') {
      clearInterval(poll);
      // Show confirmation screen
      console.log('Order completed!');
    } else if (cart.status === 'LOCKED') {
      // Payment is processing
      console.log('Processing payment...');
    }
  }, 3000); // Poll every 3 seconds

  // Stop after 2 minutes to avoid infinite polling
  setTimeout(() => clearInterval(poll), 120_000);
}

# Poll the cart endpoint
curl -X GET "https://api.craveup.com/api/v1/locations/loc_123/carts/{cartId}" \
  -H "X-API-Key: $CRAVEUP_API_KEY"

Build a status component

'use client';

import { useEffect, useState } from 'react';
import { storefront } from '@/lib/storefront';

const STEPS = [
  { status: 'OPEN', label: 'Order placed' },
  { status: 'LOCKED', label: 'Processing payment' },
  { status: 'COMPLETED', label: 'Confirmed' },
];

export function OrderStatus({
  locationId,
  cartId,
}: {
  locationId: string;
  cartId: string;
}) {
  const [currentStatus, setCurrentStatus] = useState<string>('OPEN');

  useEffect(() => {
    const poll = setInterval(async () => {
      try {
        const cart = await storefront.cart.get(locationId, cartId);
        setCurrentStatus(cart.status ?? 'OPEN');
        if (cart.status === 'COMPLETED') clearInterval(poll);
      } catch {
        // Cart may be unavailable after completion
        clearInterval(poll);
      }
    }, 3000);

    return () => clearInterval(poll);
  }, [locationId, cartId]);

  const currentIndex = STEPS.findIndex((s) => s.status === currentStatus);

  return (
    <div className="space-y-4">
      {STEPS.map((step, i) => (
        <div key={step.status} className="flex items-center gap-3">
          <div
            className={`w-8 h-8 rounded-full flex items-center justify-center text-sm font-bold ${
              i <= currentIndex
                ? 'bg-teal-600 text-white'
                : 'bg-gray-200 text-gray-500'
            }`}
          >
            {i + 1}
          </div>
          <span className={i <= currentIndex ? 'font-medium' : 'text-gray-400'}>
            {step.label}
          </span>
        </div>
      ))}
    </div>
  );
}

Confirmation page

After Stripe redirects back to your return_url, extract the cart ID and show the order summary.

import { storefront } from '@/lib/storefront';

export default async function ConfirmationPage({
  searchParams,
}: {
  searchParams: { cartId?: string };
}) {
  const cartId = searchParams.cartId;
  if (!cartId) return <p>Order not found.</p>;

  const locationId = process.env.NEXT_PUBLIC_LOCATION_ID!;
  const cart = await storefront.cart.get(locationId, cartId);

  return (
    <main className="max-w-lg mx-auto p-8">
      <h1 className="text-2xl font-bold">Order Confirmed</h1>
      <p className="text-gray-600 mt-2">
        Thank you! Your order from {cart.restaurantDisplayName} is on its way.
      </p>

      <div className="mt-6 space-y-3">
        {cart.items.map((item) => (
          <div key={item.id} className="flex justify-between">
            <span>{item.name} x{item.quantity}</span>
            <span>{item.totalFormatted}</span>
          </div>
        ))}
      </div>

      <div className="mt-6 pt-4 border-t">
        <div className="flex justify-between font-bold text-lg">
          <span>Total</span>
          <span>{cart.orderTotalWithServiceFeeFormatted}</span>
        </div>
      </div>
    </main>
  );
}

Track analytics

Fire an ORDER_PLACED analytics event for conversion tracking.

await storefront.analyticsEvents.track(locationId, {
  cartId,
  eventType: 'ORDER_PLACED',
  metadata: {
    total: cart.orderTotalWithServiceFee,
    currency: cart.currency,
    itemCount: cart.totalQuantity,
  },
});

Submit a rating

After the order is complete, prompt the customer to rate their experience.

const response = await storefront.locations.submitRating('loc_123', {
  rating: 5,
  cartId,
  comment: 'Great food and fast delivery!',
});

curl -X POST "https://api.craveup.com/api/v1/locations/loc_123/ratings" \
  -H "X-API-Key: $CRAVEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "cartId": "cart_456", "comment": "Great food!"}'

Best practices

Poll interval: 3 seconds is a good balance between responsiveness and API load
Timeout: Stop polling after 2 minutes to prevent zombie intervals
Error handling: Gracefully handle network errors during polling
Cleanup: Always clear intervals in useEffect cleanup
Caching: Store the final cart state locally to avoid unnecessary refetches on the confirmation page

Order status flow

Poll for status updates

Build a status component

Confirmation page

Track analytics

Submit a rating

Best practices

Next steps

Error Codes

SDK Reference

​Order status flow

​Poll for status updates

​Build a status component

​Confirmation page

​Track analytics

​Submit a rating

​Best practices

​Next steps

Error Codes

SDK Reference

Order status flow

Poll for status updates

Build a status component

Confirmation page

Track analytics

Submit a rating

Best practices

Next steps