Responses

Every response, success or failure, is JSON with the same three top level keys. Lists add pagination keys on top.

Envelope

{
  "success": true,
  "message": "Request was successful.",
  "data": []
}

Key	Type	Description
success	boolean	true when the request was processed, false on any error.
message	string	Short, human readable outcome. Do not parse it; use the HTTP status code and success instead.
data	array or object	The resource or list of resources. Absent on errors.

Lists also include links and meta. They are described in Pagination.

Successful list

curl "https://api.canteenweb.com/api/v1/admin/establishments" \
  -H "Authorization: Bearer your-access-token" \
  -H "X-CANTEEN-ORGANIZATION: your-org-uuid"

{
  "data": [
    {
      "uuid": "9e11ee05-32a4-4898-8735-5a7f88003409",
      "name": "Sede 1",
      "status": { "label": "Enabled", "value": "enabled" }
    }
  ],
  "links": {
    "first": "https://api.canteenweb.com/api/v1/admin/establishments?page=1",
    "last": "https://api.canteenweb.com/api/v1/admin/establishments?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.canteenweb.com/api/v1/admin/establishments",
    "per_page": 25,
    "to": 1,
    "total": 1
  },
  "success": true,
  "message": "Request was successful."
}

Money

Amounts are objects, not bare numbers. amount is the value in the smallest unit of the currency as a string (cents for ARS and USD), currency is the ISO code and formatted is what the backoffice shows, in the organization locale.

{
  "amount": "7006",
  "currency": "ARS",
  "formatted": "$ 70,06"
}

Do arithmetic on amount, display formatted.

Enumerations

Fields with a fixed set of values, such as an order status, come as an object with value (stable, use it in code) and label (translated to the organization locale, use it for display).

{
  "label": "Pendiente",
  "value": "pending"
}

Errors

Errors keep the envelope, set success to false and drop data. Validation errors add an errors object. The full list of codes and messages is in Errors.

Handling responses

const response = await fetch('https://api.canteenweb.com/api/v1/admin/orders', {
  headers: {
    'Authorization': 'Bearer your-access-token',
    'X-CANTEEN-ORGANIZATION': 'your-org-uuid',
    'Accept': 'application/json',
  },
})

const body = await response.json()

if (!response.ok || !body.success) {
  throw new Error(`Canteen API ${response.status}: ${body.message}`)
}

for (const order of body.data) {
  console.log(order.reference, order.total.formatted)
}