Server API

Three endpoints for your server. Authenticate every call with your secret key as a Bearer token.

Every request

Authorization: Bearer sk_live_...
Content-Type: application/json
Base URL: https://mealio.co

Create a session

POST /api/v1/sessions. Call this when your signed-in user is about to use the cart. Hand the token to the SDK.

Request

{ "externalUserId": "u_123" }

Response 200

{
  "sessionToken": "mst_...",
  "expiresAt": "2026-11-02T18:15:00.000Z",
  "userId": "8b1f..."
}

Field	Notes
`externalUserId`	Your own id for the user. 1 to 200 printable characters, no spaces. Mealio creates its record of the user the first time it sees the id.
`sessionToken`	Valid for 15 minutes. The SDK asks for a new one on its own when it expires, by calling the function you gave it.

Read a user's store

GET /api/v1/users/{externalUserId}/stores

Response 200

{ "defaultStore": "heb", "kroger": { "connected": true } }

Mealio cannot see whether a user is signed in to H-E-B or Safeway. That login lives only on their phone. The SDK finds out when a cart runs and shows the store's sign-in page if needed.

Delete a user

DELETE /api/v1/users/{externalUserId} removes the user and everything Mealio holds for them: saved choices, carts and their Kroger connection. Call it when your user deletes their account.

Response 200

{ "deleted": true }

Supported stores

GET /api/v1/stores is public and lists the store ids the SDK accepts right now.

Response 200

{ "stores": [
  { "id": "heb", "name": "H-E-B", "via": "device" },
  { "id": "kroger", "name": "Kroger", "via": "kroger_api" }
] }

device stores run on the user's phone with their own store login. kroger_api stores run on Mealio through Kroger's official API, after the user connects Kroger once. Pass a 5-digit zip to prepareCart for Kroger stores so Mealio can find their nearest store.

Errors

Error body

{ "error": { "code": "unauthorized", "message": "Unknown or revoked secret key." } }

Status	code	Meaning
400	`bad_external_user_id`	The external user id is empty, too long or has spaces.
401	`unauthorized`	Missing, wrong or revoked secret key.
500	`server`	Something failed on Mealio. Safe to retry.

SDK error codes

The SDK raises these to your app.

code	What to do
`login_cancelled`	The user closed the store sign-in. Let them try again.
`login_required`	The user signed in but the store still says signed out. Ask them to try again.
`store_unavailable`	The store is not answering, or Mealio switched it off for now. Show the message and try later.
`location_required`	Kroger family store with no zip. Pass a 5-digit zip.
`unsupported_store`	That store id is not supported. See /api/v1/stores.
`session_expired`	Your getSessionToken function failed twice in a row.
`network`	The phone could not reach Mealio.
`bad_envelope`	The SDK refused an instruction that failed its signature or safety checks. Contact Mealio.

There is no charge for API access yet. Pricing will be announced before it starts.