Skip to main content

Storefront Customer Favorites (v1)

Favorites for the Customer persona on the public storefront: authenticated customers persist favorites in the database; the API is only available with a valid storefront JWT.

Base path (actual backend): /v1/public/storefront/stores/:slug/auth/favorites

List favorite products​

Method & Path​

GET /api/v1/public/storefront/stores/:slug/auth/favorites

Authentication​

Required: Authorization: Bearer <storefront_access_token>

Persona access​

PersonaAccess
Customer (registered storefront user, OTP/session as implemented)Yes — own favorites only
GuestNo
Staff / Workspace Owner / AdminNo (use client/workspace APIs if needed)

Response 200 OK​

{
  "products": []
}

Products are ordered by favorite creation time (newest first). Dates are ISO strings in JSON.

Common errors​

  • 401 UNAUTHORIZED: Missing or invalid token
  • 403 FORBIDDEN: Token store does not match :slug
  • 404 NOT_FOUND: Store or user not found
  • 500 INTERNAL_SERVER_ERROR: Server error

Merge favorites (e.g. after guest session)​

Method & Path​

POST /api/v1/public/storefront/stores/:slug/auth/favorites/merge

Authentication​

Required: Bearer storefront token.

Request body​

{
  "productIds": ["507f1f77bcf86cd799439011"]
}
FieldTypeRequiredDescription
productIdsstring[]YesUp to 80 IDs; invalid or non-catalog IDs are skipped

Response 200 OK​

{
  "products": []
}

Returns the full merged favorites list as product objects.

Common errors​

  • 400 BAD_REQUEST: Invalid payload
  • 401 UNAUTHORIZED / 403 FORBIDDEN / 404 NOT_FOUND: Same as list
  • 500 INTERNAL_SERVER_ERROR: Server error

Add favorite​

Method & Path​

POST /api/v1/public/storefront/stores/:slug/auth/favorites

Authentication​

Required: Bearer storefront token.

Request body​

{
  "productId": "507f1f77bcf86cd799439011"
}

Response 204 No Content​

Empty body.

Common errors​

  • 400 BAD_REQUEST: Invalid productId
  • 404 NOT_FOUND: Product not in store or not active
  • 401 UNAUTHORIZED / 403 FORBIDDEN: Auth issues
  • 500 INTERNAL_SERVER_ERROR: Server error

Remove favorite​

Method & Path​

DELETE /api/v1/public/storefront/stores/:slug/auth/favorites/:productId

Authentication​

Required: Bearer storefront token.

Response 204 No Content​

Common errors​

  • 400 BAD_REQUEST: Invalid productId
  • 401 UNAUTHORIZED / 403 FORBIDDEN: Auth issues
  • 500 INTERNAL_SERVER_ERROR: Server error