MealMe API docs

Start here

Get a key, then choose restaurant or grocery.

MealMe gives your backend one API key. Your app passes an externalCustomerId for each end user, so carts and merchant logins stay isolated per customer.

Authorization: Bearer mm_live_your_api_key

Core concepts

The same shape works for both use cases.

TypeScript starter

One tiny server-side helper is enough to start.

Keep your MealMe API key on your backend. This typed fetch wrapper handles authentication and turns every non-2xx response into an error your app can display or log.

const MEALME_URL = "https://mealmeai.vercel.app";
const API_KEY = process.env.MEALME_API_KEY!;

async function mealme<T>(path: string, init: RequestInit = {}) {
  const response = await fetch(`${MEALME_URL}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers
    }
  });

  const body = await response.json();
  if (!response.ok) throw new Error(body.message ?? `MealMe error ${response.status}`);
  return body as T;
}

Official Node and Python SDKs are not required for the current API surface. The console’s guided checkout teaches the exact requests; SDKs should come once those contracts are stable enough to version responsibly.

Restaurant Use Case

Search restaurants, add a menu item, create checkout.

Picture a “Tinder for food” app: the user chooses a nearby restaurant, swipes through menu items, and turns the winning match into a cart. Restaurant checkout is the simpler flow because there is no customer grocery account to connect before writing the cart.

# 1. Find supported restaurants near a customer
curl 'https://mealmeai.vercel.app/api/stores/search?providerId=square&merchantType=restaurant&zipCode=45202&radiusInMiles=5&limit=5' \
  -H 'Authorization: Bearer mm_live_your_api_key'

# 2. Search that restaurant's menu
curl 'https://mealmeai.vercel.app/api/catalog/search?providerId=square&locationId=square_location_id&query=rice&limit=12' \
  -H 'Authorization: Bearer mm_live_your_api_key'

# 3. Create a MealMe cart for your customer
curl -X POST 'https://mealmeai.vercel.app/api/carts' \
  -H 'Authorization: Bearer mm_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "providerId": "square",
    "externalCustomerId": "user_123",
    "locationId": "square_location_id"
  }'

# 4. Add the menu item
curl -X POST 'https://mealmeai.vercel.app/api/carts/square_cart_id/items' \
  -H 'Authorization: Bearer mm_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "providerItemId": "square_item_id",
    "quantity": 1,
    "externalCustomerId": "user_123"
  }'

# 5. Create the restaurant checkout link.
# Include choices from item.raw.requiredModifierLists when present.
curl -X POST 'https://mealmeai.vercel.app/api/carts/square_cart_id/checkout' \
  -H 'Authorization: Bearer mm_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "unitToken": "square_unit_token",
    "menuItemId": "square_item_id",
    "menuItemVariationId": "square_variation_id",
    "modifiers": [{ "modifierId": "square_modifier_id", "quantity": 1 }],
    "quantity": 1
  }'

Grocery Use Case

Search Kroger stores, add a product, link to checkout.

Picture a meal-planning app that turns this week’s recipes into an in-app grocery cart. Search works before the shopper logs in. Cart writes require the shopper's own Kroger account because grocery carts belong to the individual customer.

# 1. Find Kroger-family grocery stores near a customer ZIP
curl 'https://mealmeai.vercel.app/api/stores/search?providerId=kroger&merchantType=grocery&zipCode=40205&radiusInMiles=25&limit=5' \
  -H 'Authorization: Bearer mm_live_your_api_key'

# 2. Search products at a selected store
curl 'https://mealmeai.vercel.app/api/catalog/search?providerId=kroger&locationId=kroger_location_id&query=milk&limit=12' \
  -H 'Authorization: Bearer mm_live_your_api_key'

# 3. Create a MealMe cart for your customer
curl -X POST 'https://mealmeai.vercel.app/api/carts' \
  -H 'Authorization: Bearer mm_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "providerId": "kroger",
    "externalCustomerId": "user_123",
    "locationId": "kroger_location_id"
  }'

# 4. Add the product. If the customer has not connected Kroger yet,
# this returns 409 kroger_customer_auth_required.
curl -X POST 'https://mealmeai.vercel.app/api/carts/kroger_cart_id/items' \
  -H 'Authorization: Bearer mm_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "providerItemId": "0001111041700",
    "quantity": 1,
    "modality": "PICKUP",
    "externalCustomerId": "user_123"
  }'

# 5. After the item is written, link out to Kroger checkout
curl -X POST 'https://mealmeai.vercel.app/api/carts/kroger_cart_id/checkout' \
  -H 'Authorization: Bearer mm_live_your_api_key'

Grocery OAuth

When Kroger needs the customer to log in.

If add-item returns 409 kroger_customer_auth_required, open the OAuth URL from /api/kroger/oauth/start. MealMe owns the Kroger callback, stores the token for your developer account plus externalCustomerId, then redirects the customer back to your redirectAfter URL.

curl -X POST 'https://mealmeai.vercel.app/api/kroger/oauth/start' \
  -H 'Authorization: Bearer mm_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalCustomerId": "user_123",
    "redirectAfter": "https://yourapp.example/kroger/connected"
  }'

After the customer returns, call the add-item endpoint again with the same externalCustomerId. Then create the checkout link.

Errors

Common responses and what to do.

Billing

Card first, then cheap usage-based billing.

Add a card before creating an API key. MealMe accrues $0.10 for each successful API call, including calls made in the guided onboarding console, and invoices usage daily after midnight UTC. There is no monthly minimum. At higher volume, switch in the dashboard to Unlimited for $250 per month.

Endpoint Reference

Endpoints