Store API

A REST API over this store's free gift data, for your own scripts, dashboards and integrations. Every response has the same shape, and each key belongs to one store.

If what you want is an AI assistant that can answer questions about the store, you want MCP instead. This surface is for code you write.

Create a key

1. In AOV.ai Free Gift, go to Settings, then the Store API section.
2. Copy the Base URL.
3. Give the key a name — the integration it is for. 1–40 characters, and it has to be distinct from your other active keys.
4. Choose its access level. Read is the default.
5. Click Create key.

The key is shown once, with a ready-to-run curl and Node example underneath.

Access levels

A key carries one of three levels, and it is enforced on every request.

A read key that calls a write endpoint gets INSUFFICIENT_SCOPE (403) — a clear refusal rather than a 404, so an integration failing this way tells you which of the two problems it has.

Your first request

curl "https://upsell.avada.io/store-api/v1/campaigns" \
  -H "Authorization: Bearer aov_sk_YOUR_KEY"

const res = await fetch('https://upsell.avada.io/store-api/v1/analytics?days=7', {
  headers: {Authorization: 'Bearer aov_sk_YOUR_KEY'}
});
const {success, data, error} = await res.json();

Every response has the same shape

{"success": true, "data": { }, "error": null}

On failure, success is false, data is null, and error carries a stable code and a message meant to be read by a person:

{"success": false, "data": null, "error": {"code": "INVALID_INPUT", "message": "…"}}

Branch on error.code, not on the message. Codes are stable; wording is not. The HTTP status carries the same meaning, so a client that only checks the status is also correct. Both are listed in Errors.

The API describes itself

GET /store-api/v1 returns the endpoint list, with each path, its summary, and the query parameters it accepts. It is generated from the same table that builds the routes, so it cannot fall out of date with what actually exists.

It requires a key like everything else under the prefix.

Never call this from a browser

The API sends permissive CORS headers, so a request from browser JavaScript will succeed. That is there for server-side tools and local development, not for your storefront.

Keys are per surface

Free Gift issues two kinds of key and they are not interchangeable:

Present an aov_mcp_ key here and the response says so by name — WRONG_SURFACE — rather than reporting it invalid, because the fix is to mint the right kind of key, not to hunt for a typo. Revoking one surface never affects the other.

Losing the plan revokes your keys

Every other refusal on this API is temporary: fix the cause and the same key resumes working. Loss of the paid plan is not.

This is deliberate. Billing changes do not all pass through this app, so the first refused request is the reliable moment to act on one; and keys left dormant would otherwise all wake up together on the day a store is reinstated, with nobody having decided that they should.

Limits

A rate limit is counted per key, so one integration cannot exhaust another's budget. Requests are counted before the key is even resolved, which means a flood of bad keys is throttled too.

What is never returned

• No customer data. No names, emails, addresses, or individual orders. Analytics figures are aggregates over a date range.
• No credentials or internal ids. The store's Shopify access token, its internal record id, and the key's own fingerprint are stripped before anything leaves the server.
• No silent writes. Creating, editing and deleting each take a confirmation token from a preview call that writes nothing, so a change is always validated and returned to you before it is applied.
• No plan changes. Nothing on this surface alters billing, and no endpoint quotes a price.

Where next

• Endpoints — all twenty-six, with their parameters and access levels
• Errors — every code, what causes it, what to do
• MCP tool guide — the meaning of the fields each endpoint returns