Developers

Setup Guides & API Reference

Connect Shopify or WooCommerce in about 10 minutes, then use the REST API to sync your product catalog, manage webhooks, and read the blog feed programmatically. Base URL: https://valyupeak.com

Looking for how to use a feature or setting? Visit the Help Center.

Setup Guides

Connect your store first, then use the API below for custom integrations. No developer is needed for either setup.

How to connect Shopify to Valyupeak

Connect a Shopify store to Valyupeak with a one-click app install, sync your catalog, and start tracking competitor prices. Takes about 10 minutes.

1
Create a free account
Sign up at valyupeak.com. Valyupeak is free during beta and no credit card is required.
2
Open Integrations
In the dashboard, go to Settings → Integrations and click Connect on the Shopify card.
3
Enter your store domain
Type your store's myshopify.com domain (for example yourstore.myshopify.com). You are sent to Shopify to approve the connection.
4
Approve the app in Shopify
Review the requested permissions in your Shopify admin and approve the install. You are returned to Valyupeak automatically.
5
Sync your products
Click Sync Products. Your Shopify catalog, including variants, SKUs and prices, is imported into Valyupeak.
6
Add costs and a margin floor
In Catalog, open a product and enter its cost and minimum price. Repricing never goes below this floor.
7
Add competitors and match products
Add competitor product URLs and match each one to your product by SKU, GTIN or name. Prices are then tracked automatically.

How to connect WooCommerce to Valyupeak

Install the free Valyupeak plugin for WooCommerce, connect it with an API key, and see competitor prices inside your WordPress admin. Takes about 10 minutes.

1
Create a free account
Sign up at valyupeak.com. Valyupeak is free during beta and no credit card is required.
2
Generate an API key
In the dashboard, go to Settings → Integrations and create an API key. Copy it; you will paste it into WordPress.
3
Install the plugin
In WordPress, go to Plugins → Add New, search for "Valyupeak", then install and activate the plugin.
4
Connect your store
Go to WooCommerce → Valyupeak, paste your API key and click Test connection to link your store.
5
Choose products and competitors
Select the products and competitor stores you want to track. Competitor prices then appear next to yours on the WooCommerce Products screen.
6
Apply suggested prices
Review undercut alerts and apply a suggested price with one click. Suggestions always stay above your margin floor.

Authentication

The Valyupeak API uses two authentication schemes depending on the endpoint.

API KeyBearer token

Used for machine-to-machine integrations. Generate a key in Dashboard → Settings → Integrations. Pass it in the Authorization header.

Authorization: Bearer vp_live_abc123...

Session CookieClerk session

Used when calling the API from a signed-in browser context. The Clerk session cookie is automatically sent by the browser — no extra setup required.

Cookie: __session=<clerk_token>

⚠API keys grant full access to your workspace data. Never expose them in client-side code or public repositories. Rotate compromised keys immediately in Dashboard → Settings → Integrations.

Catalog Products

Read and update your catalog products. Useful for syncing prices from your own ERP or inventory system into Valyupeak so the repricing engine always has your latest cost data.

All /api/v1/internal-products endpoints require API Key authentication.

GET/api/v1/internal-productsAPI Key

Returns all catalog products in the workspace associated with the API key. Optionally filter by SKU.

Query parameters

Param	Type	Required	Description
sku	string	No	Filter results to the product with this exact SKU.

Response

{
  "success": true,
  "count": 2,
  "products": [
    {
      "id": "clxyz...",
      "name": "Wireless Earbuds Pro",
      "sku": "WEP-001",
      "price": 79.99,
      "minPrice": 49.99,
      "url": "https://yourstore.com/products/wep-001",
      "category": { "id": "...", "name": "Electronics" },
      "productMatches": [
        {
          "isRepricingEnabled": true,
          "trackedProduct": {
            "name": "Competitor Earbuds",
            "currentPrice": 74.99
          }
        }
      ]
    }
  ]
}

PATCH/api/v1/internal-productsAPI Key

Update the price and/or minimum price floor for a product identified by SKU. Use this to push cost or list-price changes from your ERP into Valyupeak so the repricing engine recalculates correctly.

Request body (JSON)

Field	Type	Required	Description
sku	string	Yes	The SKU of the product to update.
price	number	No	New current / list price.
minPrice	number	No	New minimum price floor. The repricing engine will never go below this value.

Response

{
  "success": true,
  "product": {
    "id": "clxyz...",
    "sku": "WEP-001",
    "price": 84.99,
    "minPrice": 52.00,
    ...
  }
}

At least one of price or minPrice must be present. SKU matching is case-sensitive.

Webhooks

Register HTTPS endpoints to receive real-time event notifications — price changes, stock alerts, and repricing actions — as they happen.

Webhook management endpoints require Session Cookie authentication (signed-in user). Events are delivered to your registered URL using API Key authentication — see the Webhook Events section for the payload schema.

GET/api/v1/webhooksSession

Returns all webhook endpoints registered for the specified workspace.

Query parameters

Param	Type	Required	Description
workspaceId	string	Yes	The ID of the workspace whose webhook endpoints to list.

Response

{
  "success": true,
  "endpoints": [
    {
      "id": "clxyz...",
      "url": "https://yourserver.com/hooks/valyupeak",
      "isActive": true,
      "workspaceId": "...",
      "createdAt": "2025-06-01T10:00:00.000Z"
    }
  ]
}

POST/api/v1/webhooksSession

Register a new webhook endpoint for a workspace. A random 64-character HMAC secret is generated and returned once — store it securely, as it cannot be retrieved afterwards.

Request body (JSON)

Field	Type	Required	Description
workspaceId	string	Yes	The workspace this webhook belongs to.
url	string	Yes	Your HTTPS endpoint URL. Must be publicly reachable.
isActive	boolean	No	Whether to start delivering events immediately. Defaults to true.

Response

{
  "success": true,
  "endpoint": {
    "id": "clxyz...",
    "url": "https://yourserver.com/hooks/valyupeak",
    "secret": "a3f8e2c1d4b7...",
    "isActive": true,
    "workspaceId": "..."
  }
}

The secret field is only returned on creation. Use it to verify the X-Valyupeak-Signature header on incoming events.

Blog Feed

A public JSON feed of all Valyupeak blog posts. No authentication required. Intended for AI agents, RSS readers, and integrations that want to embed our content.

GET/api/v1/blogPublic

Returns a JSON array of all published blog posts, sorted by date descending. Includes full metadata: title, slug, description, tags, author, cover image, and published date.

Response

{
  "posts": [
    {
      "slug": "how-to-beat-competitors-on-price",
      "title": "How to Beat Competitors on Price Without a Race to the Bottom",
      "description": "A practical guide to intelligent repricing...",
      "date": "2025-05-15",
      "author": "valyupeak-team",
      "tags": ["repricing", "strategy"],
      "coverImage": "/blog/covers/repricing-guide.jpg",
      "readingTime": "6 min read"
    }
  ]
}

This endpoint is explicitly allowed in robots.txt for AI crawlers (ClaudeBot, GPTBot, PerplexityBot).

Webhook Event Reference

All events are delivered as HTTP POST requests to your registered endpoint with the following envelope structure. Verify authenticity using the HMAC signature.

Envelope

POST https://yourserver.com/hooks/valyupeak
Content-Type: application/json
X-Valyupeak-Signature: <hmac-sha256-hex>

{
  "id": "evt_1748000000000_abc123",
  "type": "price.changed",
  "created": "2025-06-01T14:32:00.000Z",
  "data": { ... }
}

Signature verification (Node.js example)

import { createHmac } from "crypto";

function isValidSignature(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return expected === signature;
}

// In your route handler:
const rawBody = await request.text();
const sig     = request.headers.get("x-valyupeak-signature") ?? "";
if (!isValidSignature(rawBody, sig, process.env.VALYUPEAK_WEBHOOK_SECRET!)) {
  return new Response("Forbidden", { status: 403 });
}

Event types

Event type	Triggered when
price.changed	A tracked product's price changes above your configured threshold
stock.out	A tracked product goes out of stock
stock.recovered	A previously out-of-stock product becomes available again
promo.changed	A competitor's promotional text appears, changes, or disappears
url.broken	A tracked product URL returns 404 / becomes unreachable
url.recovered	A previously broken URL becomes reachable again
schema.improved	A competitor's schema score increases by 10+ points
gtin.added	A competitor adds a GTIN/barcode to a product listing
description.changed	A competitor updates their product description
listing.changed	A competitor adds or removes product images

Rate Limits

To maintain reliability for all users, the API enforces the following limits:

Endpoint group	Limit
/api/v1/internal-products (read)	120 requests / minute
/api/v1/internal-products (write)	30 requests / minute
/api/v1/webhooks	60 requests / minute
/api/v1/blog	Unlimited (public, cached)

Rate-limited responses return HTTP 429 Too Many Requests. If you need higher limits for a specific integration, contact hello@valyupeak.com.

← Back to Valyupeak