Shopping List Endpoints: Manage Household Lists & Items

Shopping lists in FridgeRadar are scoped to a household (id_hogar) and can be populated with individual product items, each carrying optional quantity, unit, priority, and note fields. Lists move through states (e.g. activa, completada) and items can be marked as comprado as you shop. All routes require a valid Bearer token.

Create Shopping List

Creates a new shopping list for a household. You may optionally include an initial array of items in the same request.

id_hogar

integer

required

ID of the household the list belongs to.

nombre

string

Optional display name for the list (e.g. "Compras del fin de semana").

items

array

Optional array of ListaCompraDetalleCreate objects to add to the list on creation. Defaults to an empty array.

POST /api/v1/listas-compra
Response 201

curl -X POST "https://api.fridgeradar.app/api/v1/listas-compra" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_hogar": 3,
    "nombre": "Compras del fin de semana",
    "items": [
      { "id_producto": 12, "cantidad": 2, "unidad": "litros", "prioridad": "alta" }
    ]
  }'

{
  "id_lista": 9,
  "id_hogar": 3,
  "nombre": "Compras del fin de semana",
  "estado": "activa",
  "fecha_creacion": "2024-06-10T09:00:00",
  "items": [
    {
      "id_detalle": 21,
      "id_lista": 9,
      "id_producto": 12,
      "cantidad": 2.0,
      "unidad": "litros",
      "prioridad": "alta",
      "comprado": false,
      "nota": null
    }
  ]
}

Response fields — ListaCompraResponse

id_lista

integer

required

Unique identifier for the shopping list.

id_hogar

integer

required

ID of the household that owns this list.

nombre

string | null

Display name of the list, or null if none was provided.

estado

string

required

Current state of the list, e.g. activa or completada.

fecha_creacion

string (datetime)

required

ISO 8601 timestamp of when the list was created.

items

array

Array of ListaCompraDetalleResponse objects associated with this list.

List Shopping Lists for a Household

Returns all shopping lists belonging to the specified household.

id_hogar

integer

required

ID of the household whose shopping lists to retrieve.

GET /api/v1/listas-compra
Response 200

curl -X GET "https://api.fridgeradar.app/api/v1/listas-compra?id_hogar=3" \
  -H "Authorization: Bearer <token>"

[
  {
    "id_lista": 9,
    "id_hogar": 3,
    "nombre": "Compras del fin de semana",
    "estado": "activa",
    "fecha_creacion": "2024-06-10T09:00:00",
    "items": []
  }
]

Get One Shopping List

Retrieves a single shopping list by ID, including all its items.

id_lista

integer

required

The unique identifier of the shopping list.

GET /api/v1/listas-compra/{id_lista}
Response 200

curl -X GET "https://api.fridgeradar.app/api/v1/listas-compra/9" \
  -H "Authorization: Bearer <token>"

{
  "id_lista": 9,
  "id_hogar": 3,
  "nombre": "Compras del fin de semana",
  "estado": "activa",
  "fecha_creacion": "2024-06-10T09:00:00",
  "items": [
    {
      "id_detalle": 21,
      "id_lista": 9,
      "id_producto": 12,
      "cantidad": 2.0,
      "unidad": "litros",
      "prioridad": "alta",
      "comprado": false,
      "nota": null
    }
  ]
}

Update Shopping List

Partially updates a shopping list’s nombre or estado. Only provided fields are changed.

id_lista

integer

required

The unique identifier of the shopping list to update.

nombre

string

New display name for the list.

estado

string

New state for the list, e.g. completada.

PATCH /api/v1/listas-compra/{id_lista}
Response 200

curl -X PATCH "https://api.fridgeradar.app/api/v1/listas-compra/9" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "estado": "completada" }'

{
  "id_lista": 9,
  "id_hogar": 3,
  "nombre": "Compras del fin de semana",
  "estado": "completada",
  "fecha_creacion": "2024-06-10T09:00:00",
  "items": []
}

Delete Shopping List

Permanently deletes a shopping list and all its items. Returns 204 No Content on success.

id_lista

integer

required

The unique identifier of the shopping list to delete.

DELETE /api/v1/listas-compra/{id_lista}
Response 204

curl -X DELETE "https://api.fridgeradar.app/api/v1/listas-compra/9" \
  -H "Authorization: Bearer <token>"

(No content)

Add Item to Shopping List

Adds a single product item to an existing shopping list. Returns 201 Created with the new item.

id_lista

integer

required

The unique identifier of the shopping list to add the item to.

id_producto

integer

required

ID of the product to add to the list.

cantidad

float

Optional quantity of the product needed.

unidad

string

Optional unit of measurement (e.g. "kg", "litros", "unidades").

prioridad

string

default:"media"

Shopping priority. Accepted values: alta, media, baja. Defaults to media.

nota

string

Optional free-text note for this item (e.g. brand preference).

POST /api/v1/listas-compra/{id_lista}/items
Response 201

curl -X POST "https://api.fridgeradar.app/api/v1/listas-compra/9/items" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_producto": 5,
    "cantidad": 1,
    "unidad": "kg",
    "prioridad": "baja",
    "nota": "Marca La Serenísima"
  }'

{
  "id_detalle": 34,
  "id_lista": 9,
  "id_producto": 5,
  "cantidad": 1.0,
  "unidad": "kg",
  "prioridad": "baja",
  "comprado": false,
  "nota": "Marca La Serenísima"
}

Response fields — ListaCompraDetalleResponse

id_detalle

integer

required

Unique identifier for this list item.

id_lista

integer

required

ID of the shopping list this item belongs to.

id_producto

integer

required

ID of the product referenced by this item.

cantidad

float | null

Quantity of the product required, or null if unspecified.

unidad

string | null

Unit of measurement, or null if unspecified.

prioridad

string

required

Shopping priority: alta, media, or baja.

comprado

boolean

required

true if the item has been purchased, false otherwise.

nota

string | null

Optional note attached to this item, or null.

Update List Item

Partially updates a shopping list item. Any combination of fields can be sent; only provided fields are changed.

id_detalle

integer

required

The unique identifier of the item to update.

cantidad

float

Updated quantity.

unidad

string

Updated unit of measurement.

prioridad

string

Updated priority: alta, media, or baja.

comprado

boolean

Set to true to mark the item as purchased.

nota

string

Updated note for this item.

PATCH /api/v1/listas-compra/items/{id_detalle}
Response 200

curl -X PATCH "https://api.fridgeradar.app/api/v1/listas-compra/items/34" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "comprado": true }'

{
  "id_detalle": 34,
  "id_lista": 9,
  "id_producto": 5,
  "cantidad": 1.0,
  "unidad": "kg",
  "prioridad": "baja",
  "comprado": true,
  "nota": "Marca La Serenísima"
}

Delete List Item

Permanently removes a single item from a shopping list. Returns 204 No Content on success.

id_detalle

integer

required

The unique identifier of the item to delete.

DELETE /api/v1/listas-compra/items/{id_detalle}
Response 204

curl -X DELETE "https://api.fridgeradar.app/api/v1/listas-compra/items/34" \
  -H "Authorization: Bearer <token>"

(No content)

Overview

Endpoints

Shopping List Endpoints: Manage Household Lists & Items

Create Shopping List

List Shopping Lists for a Household

Get One Shopping List

Update Shopping List

Delete Shopping List

Add Item to Shopping List

Update List Item

Delete List Item

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Create Shopping List

​List Shopping Lists for a Household

​Get One Shopping List

​Update Shopping List

​Delete Shopping List

​Add Item to Shopping List

​Update List Item

​Delete List Item

Build docs developers (and LLMs) love

Create Shopping List

List Shopping Lists for a Household

Get One Shopping List

Update Shopping List

Delete Shopping List

Add Item to Shopping List

Update List Item

Delete List Item