API Reference

Introduction

The NativeProof API allows you to interact with product reviews on your Shopify storefront. All API access is provided through Shopify's App Proxy, which means requests are authenticated automatically using Shopify's OAuth infrastructure.

What You Can Do

• Submit new product reviews from your storefront
• Retrieve reviews for any product by handle
• Get aggregate rating statistics
• Access the Google Shopping XML feed

Authentication

NativeProof uses Shopify's App Proxy for all storefront API calls. This means:

• Automatic authentication: Requests through your store's proxy URL include Shopify's HMAC signature
• Shop context: The shop domain is automatically determined from the proxy request
• No API keys to manage: Authentication is handled by Shopify's infrastructure

Base URL

All API requests are made through Shopify's App Proxy at your store's domain:

https://your-store.myshopify.com/apps/reviews

Replace your-store.myshopify.com with your actual Shopify store domain. If you have a custom domain, that will work too:

https://www.yourstore.com/apps/reviews

App Proxy Endpoints

curl -X POST https://your-store.myshopify.com/apps/reviews/submit \
  -H "Content-Type: application/json" \
  -d '{
    "product_handle": "classic-leather-jacket",
    "rating": 5,
    "title": "Amazing quality!",
    "body": "This jacket exceeded my expectations. The leather is soft and the fit is perfect.",
    "author_name": "John D.",
    "author_email": "john@example.com"
  }'

const response = await fetch('/apps/reviews/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product_handle: 'classic-leather-jacket',
    rating: 5,
    title: 'Amazing quality!',
    body: 'This jacket exceeded my expectations.',
    author_name: 'John D.',
    author_email: 'john@example.com'
  })
});

const data = await response.json();
console.log(data);
// { success: true, review_id: "rv_abc123..." }

{
  "success": true,
  "review_id": "rv_abc123def456",
  "message": "Review submitted successfully",
  "status": "pending"
}

Webhooks

NativeProof listens to Shopify webhooks to provide features like verified buyer detection and GDPR compliance. These webhooks are automatically registered when you install the app.

Webhook Events

Metaobject Schema

Reviews are stored in Shopify Metaobjects for zero-latency server-side rendering. This schema is automatically created when you install the app.

Review Metaobject Fields

Google Shopping Feed

NativeProof automatically generates a Google Product Review XML feed that conforms to Google Merchant Center specifications.

https://your-store.myshopify.com/apps/reviews/feed.xml

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <version>2.3</version>
  <publisher>
    <name>Your Store Name</name>
  </publisher>
  <reviews>
    <review>
      <review_id>rv_abc123</review_id>
      <reviewer>
        <name>John D.</name>
      </reviewer>
      <review_timestamp>2025-01-07T10:30:00Z</review_timestamp>
      <title>Amazing quality!</title>
      <content>This jacket exceeded my expectations.</content>
      <ratings>
        <overall min="1" max="5">5</overall>
      </ratings>
      <products>
        <product>
          <product_ids>
            <gtins>
              <gtin>1234567890123</gtin>
            </gtins>
          </product_ids>
          <product_name>Classic Leather Jacket</product_name>
        </product>
      </products>
      <is_spam>false</is_spam>
    </review>
  </reviews>
</feed>

Rate Limits

To ensure fair usage and maintain service quality, the following rate limits apply:

Error Codes

The API uses standard HTTP status codes to indicate success or failure of requests.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "fields": {
      "rating": "Rating must be between 1 and 5",
      "author_email": "Invalid email format"
    }
  }
}