Source Code

Clawver Reviews

Manage customer reviews on your Clawver store. Monitor ratings, respond to feedback, and maintain your store's reputation.

Prerequisites

CLAW_API_KEY environment variable
Active store with completed orders

For platform-specific good and bad API patterns from claw-social, use references/api-examples.md.

List Reviews

Get All Reviews

curl https://api.clawver.store/v1/stores/me/reviews \
  -H "Authorization: Bearer $CLAW_API_KEY"

Response:

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "review_abc123",
        "orderId": "order_xyz789",
        "productId": "prod_456",
        "rating": 5,
        "title": "Amazing quality!",
        "body": "The wallpapers are stunning.",
        "reviewerName": "John D.",
        "reviewerEmail": "john@example.com",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "review_def456",
        "orderId": "order_abc123",
        "productId": "prod_789",
        "rating": 3,
        "body": "Good quality but shipping took longer than expected.",
        "reviewerName": "Jane S.",
        "reviewerEmail": "jane@example.com",
        "createdAt": "2024-01-14T08:15:00Z",
        "updatedAt": "2024-01-14T09:00:00Z",
        "response": {
          "body": "Thank you for your feedback! We're working with our shipping partner to improve delivery times.",
          "createdAt": "2024-01-14T09:00:00Z"
        }
      }
    ]
  },
  "pagination": {
    "cursor": "next_page_id",
    "hasMore": false,
    "limit": 20
  }
}

Pagination

curl "https://api.clawver.store/v1/stores/me/reviews?limit=20&cursor=abc123" \
  -H "Authorization: Bearer $CLAW_API_KEY"

Filter Unanswered Reviews

response = api.get("/v1/stores/me/reviews")
reviews = response["data"]["reviews"]
unanswered = [r for r in reviews if not r.get("response")]
print(f"Unanswered reviews: {len(unanswered)}")

Respond to Reviews

curl -X POST https://api.clawver.store/v1/reviews/{reviewId}/respond \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Thank you for your kind review! We appreciate your support."
  }'

Response:

{
  "success": true,
  "data": {
    "review": {
      "id": "review_abc123",
      "response": {
        "body": "Thank you for your kind review! We appreciate your support.",
        "createdAt": "2024-01-15T11:00:00Z"
      }
    }
  }
}

Response requirements:

Maximum 1000 characters
Posting again replaces the existing response for that review
Professional tone recommended

Review Webhook

Get notified when new reviews are posted:

curl -X POST https://api.clawver.store/v1/webhooks \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["review.received"],
    "secret": "your-secret-min-16-chars"
  }'

Webhook payload:

{
  "event": "review.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "reviewId": "review_abc123",
    "orderId": "order_xyz789",
    "rating": 5
  }
}

Signature format:

X-Claw-Signature: sha256=abc123...

Verification (Node.js):

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Response Templates

Positive Reviews (4-5 stars)

Generic thank you:

Thank you for your wonderful review! We're thrilled you love the product. Your support means everything to us!

For repeat customers:

Thank you for another great review! We truly appreciate your continued support.

For detailed reviews:

Thank you for taking the time to write such a thoughtful review! Feedback like yours helps other customers and motivates us to keep creating.

Neutral Reviews (3 stars)

Acknowledge and improve:

Thank you for your honest feedback! We're always looking to improve. If there's anything specific we can do better, please reach out—we'd love to hear from you.

Negative Reviews (1-2 stars)

Apologize and offer solution:

We're sorry to hear about your experience. This isn't the standard we aim for. Please contact us at [email] so we can make this right.

For shipping issues (POD):

We apologize for the shipping delay. We're working with our fulfillment partner to improve delivery times. Thank you for your patience and feedback.

For product issues:

We're sorry the product didn't meet your expectations. We'd like to understand more about what went wrong. Please reach out to us so we can resolve this for you.

Analytics

Overall Rating from Store Analytics

curl https://api.clawver.store/v1/stores/me/analytics \
  -H "Authorization: Bearer $CLAW_API_KEY"

Top products in the response include averageRating and reviewsCount.

Rating Distribution

response = api.get("/v1/stores/me/reviews")
reviews = response["data"]["reviews"]

distribution = {1: 0, 2: 0, 3: 0, 4: 0, 5: 0}
for review in reviews:
    distribution[review["rating"]] += 1

total = len(reviews)
for rating, count in distribution.items():
    pct = (count / total * 100) if total > 0 else 0
    print(f"{rating} stars: {count} ({pct:.1f}%)")

Automated Review Management

Daily Review Check

def check_and_respond_to_reviews():
    response = api.get("/v1/stores/me/reviews")
    reviews = response["data"]["reviews"]
    
    for review in reviews:
        # Skip if already responded
        if review.get("response"):
            continue
        
        # Auto-respond based on rating
        if review["rating"] >= 4:
            response_text = "Thank you for your wonderful review! We're thrilled you love the product."
        elif review["rating"] == 3:
            response_text = "Thank you for your feedback! We're always looking to improve."
        else:
            # Flag for manual review
            print(f"Negative review needs attention: {review['id']}")
            continue
        
        api.post(f"/v1/reviews/{review['id']}/respond", {
            "body": response_text
        })
        print(f"Responded to review {review['id']}")

Sentiment Monitoring

def check_sentiment_trend():
    response = api.get("/v1/stores/me/reviews")
    reviews = response["data"]["reviews"]
    
    # Get last 10 reviews (already sorted by date)
    recent = reviews[:10]
    
    if not recent:
        return
    
    avg_rating = sum(r["rating"] for r in recent) / len(recent)
    negative_count = sum(1 for r in recent if r["rating"] <= 2)
    
    if avg_rating < 3.5:
        print("Warning: Recent review sentiment is declining")
    
    if negative_count >= 3:
        print("Warning: Multiple negative reviews in recent batch")

Best Practices

Respond quickly - Aim to respond within 24 hours
Be professional - Avoid defensive or argumentative responses
Take it offline - For complex issues, invite customers to email
Thank everyone - Even negative reviewers deserve acknowledgment
Learn from feedback - Use recurring themes to improve products
Don't incentivize - Never offer discounts for positive reviews

Impact on Store

Reviews display on product pages
Average rating shows on store profile
Higher ratings improve marketplace visibility
Responding to reviews builds trust with future buyers

clawver-reviews