Skip to main content

​
Overview

The Shopping API allows you to create, read, update, delete, and reorder shopping list items. Each item includes a name and category for organization.

​
Endpoints

​
Get All Shopping Items

​
GET /api/shopping
endpoint
Retrieves all shopping items for the authenticated user’s household, ordered by position.
Authentication: Required Response
​
items
array
Array of shopping item objects
curl -X GET https://your-domain.com/api/shopping \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response 
[
  {
    "id": "clx123abc",
    "householdId": "clx456def",
    "name": "Milk",
    "category": "Dairy",
    "position": 0,
    "checked": false,
    "createdAt": "2024-03-15T10:00:00Z"
  },
  {
    "id": "clx789ghi",
    "householdId": "clx456def",
    "name": "Bananas",
    "category": "Produce",
    "position": 1,
    "checked": false,
    "createdAt": "2024-03-15T11:00:00Z"
  }
]

​
Create or Reorder Shopping Items

​
POST /api/shopping
endpoint
Creates a new shopping item or reorders existing items.
Authentication: Required Request Body (Create) Request Body (Reorder) 
curl -X POST https://your-domain.com/api/shopping \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Eggs",
    "category": "Dairy"
  }'
Response (Create) 
{
  "id": "clxnew123",
  "householdId": "clx456def",
  "name": "Eggs",
  "category": "Dairy",
  "position": 2,
  "checked": false,
  "createdAt": "2024-03-15T12:00:00Z"
}
Response (Reorder) 
Positions updated
Status: 200 OK

​
Update Shopping Item

​
POST /api/shopping/update
endpoint
Updates an existing shopping item’s details.
Authentication: Required Request Body 
curl -X POST https://your-domain.com/api/shopping/update \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "clx123abc",
    "name": "Whole Milk",
    "category": "Dairy"
  }'
Response 
{
  "count": 1
}

​
Delete Shopping Item

​
POST /api/shopping/delete
endpoint
Deletes (marks as purchased) a shopping item and creates a notification.
Authentication: Required Request Body 
curl -X POST https://your-domain.com/api/shopping/delete \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "clx123abc"}'
Response 
{
  "id": "clx123abc",
  "householdId": "clx456def",
  "name": "Milk",
  "category": "Dairy",
  "position": 0,
  "checked": false,
  "createdAt": "2024-03-15T10:00:00Z"
}
When a shopping item is deleted, a notification is automatically created with:
  • Type: “shopping”
  • Title: “Item Removed”
  • Body: “You completed: [item name]“

​
Get Shopping Items Count

​
GET /api/shopping/count
endpoint
Returns the total number of shopping items for the household.
Authentication: Required 
curl -X GET https://your-domain.com/api/shopping/count \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Response 
{
  "count": 12
}
The count endpoint returns {"count": 0} if the user is unauthorized, rather than throwing an error. This is different from other count endpoints.

​
Error Responses

​
401 Unauthorized
User is not authenticated (returns {"count": 0} for count endpoint)
Unauthorized
​
400 Bad Request
Missing required fields
Missing fields
or 
Missing ID
​
500 Internal Server Error
Unexpected server error
Internal Server Error

​
Source Code Reference

  • Main routes: ~/workspace/source/src/app/api/shopping/route.ts:18
  • Count endpoint: ~/workspace/source/src/app/api/shopping/count/route.ts:18
  • Delete endpoint: ~/workspace/source/src/app/api/shopping/delete/route.ts:19
  • Update endpoint: ~/workspace/source/src/app/api/shopping/update/route.ts:18

Build docs developers (and LLMs) love

Get started for freeTalk to us