Skip to main content
POST
https://app.uselayers.com/api/storefront/v1
/
search
/
feedback
Search Feedback API
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/feedback \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "search_id": "<string>",
  "rating": "<string>",
  "text_feedback": "<string>",
  "product_feedback": [
    {
      "product_id": 123,
      "rating": "<string>",
      "feedback": "<string>"
    }
  ],
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  }
}
'
{
  "id": "01HZY7K2M8N9P4Q5R6S7T8U9V0",
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG",
  "recorded": true
}
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

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

​
Headers

​
Content-Type
string
default:"application/json"
required
​
Accept
string
default:"application/json"
required

​
Body

​
search_id
string
required
ULID identifier of the search to provide feedback on. This should be the search_id returned from the Prepare Search endpoint.
​
rating
string
Overall rating for the search results. Must be one of:
  • "positive" - Thumbs up, results were helpful
  • "negative" - Thumbs down, results were not helpful
​
text_feedback
string
Free-form text feedback from the user. Maximum 2000 characters.
​
product_feedback
array
Array of product-specific feedback objects. Each object contains:
​
identity
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

​
id
string
ULID identifier for the created feedback record.
​
search_id
string
The search ID that was provided in the request.
​
recorded
boolean
Always true when feedback is successfully recorded.
{
  "id": "01HZY7K2M8N9P4Q5R6S7T8U9V0",
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG",
  "recorded": true
}

​
Error Conditions

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

​
Example Usage

​
Basic rating feedback

const response = await fetch('https://api.layers.ai/api/storefront/v1/search/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Storefront-Access-Token': 'your-token-here'
  },
  body: JSON.stringify({
    search_id: '01HZY7J9ZV6K2T3M6P4FJ3F2QG',
    rating: 'positive'
  })
});

const data = await response.json();
console.log(data);
// { id: "01HZY7K2M8N9P4Q5R6S7T8U9V0", search_id: "01HZY7J9ZV6K2T3M6P4FJ3F2QG", recorded: true }

​
Feedback with text and identity

const response = await fetch('https://api.layers.ai/api/storefront/v1/search/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Storefront-Access-Token': 'your-token-here'
  },
  body: JSON.stringify({
    search_id: '01HZY7J9ZV6K2T3M6P4FJ3F2QG',
    rating: 'negative',
    text_feedback: 'The results were not relevant to my search.',
    identity: {
      sessionId: 'session-123',
      customerId: 'customer-456'
    }
  })
});

const data = await response.json();

​
Product-specific feedback

const response = await fetch('https://api.layers.ai/api/storefront/v1/search/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Storefront-Access-Token': 'your-token-here'
  },
  body: JSON.stringify({
    search_id: '01HZY7J9ZV6K2T3M6P4FJ3F2QG',
    product_feedback: [
      {
        product_id: 123,
        rating: 'positive'
      },
      {
        product_id: 456,
        rating: 'negative',
        feedback: 'Not what I was looking for'
      }
    ]
  })
});

const data = await response.json();

​
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