Skip to main content
POST
Text Search: Submit Feedback
This endpoint allows you to capture user feedback on search results, including overall ratings, text feedback, and product-specific feedback. When feedback is submitted, the endpoint retrieves the cached search data (if still available) and stores the original search query, expanded queries, and intent modifier actions alongside the feedback for analysis.

Authorization

string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>. Same requirements as the Search API.

Headers

string
default:"application/json"
required
string
default:"application/json"
required

Body

string
required
ULID identifier of the search to provide feedback on. This should be the search_id returned from the Prepare Search endpoint.
string
Overall rating for the search results. Must be one of:
  • "positive" - Thumbs up, results were helpful
  • "negative" - Thumbs down, results were not helpful
string
Free-form text feedback from the user. Maximum 2000 characters.
array
Array of product-specific feedback objects. Each object contains:
object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.

Validation rules

  • search_id is required and must be a valid ULID
  • rating must be either "positive" or "negative" if provided
  • text_feedback has a maximum length of 2000 characters
  • product_feedback is an array where each item must include:
    • product_id (required when product_feedback is provided)
    • rating must be "positive" or "negative" if provided
    • feedback has a maximum length of 500 characters
  • At least one of rating, text_feedback, or product_feedback should be provided, though all fields are technically optional

Behavior

  • Returns HTTP 201 (Created) when feedback is successfully recorded
  • Attempts to retrieve cached search data using the provided search_id
  • If cached data is available (within 15 minutes of the original search), captures:
    • Original search query
    • Expanded queries used for search
    • Intent modifier actions applied
  • If cached data is not available (expired or invalid search_id), feedback is still recorded but without the search context
  • Stores identity information (sessionId and customerId) if provided

Response

201 Created

string
ULID identifier for the created feedback record.
string
The search ID that was provided in the request.
boolean
Always true when feedback is successfully recorded.

Error conditions

  • 401 Unauthorized: Missing or invalid X-Storefront-Access-Token
  • 422 Unprocessable Entity: Invalid body or validation errors

Example usage

Basic rating feedback

Feedback with text and identity

Product-specific feedback

Next steps

  • Use this endpoint in conjunction with the Prepare Search and Search endpoints to create a complete search experience with feedback collection
  • Analyze collected feedback to improve search relevance and user experience