Cove Wishlist for developers

Cove Wishlist works as it is, or you can build on it: read and change wishlists from your own server, or build your own wishlist UI on the storefront. Nothing to install: no SDK, no script tags.

1. REST API
2. Authentication
3. Rate limits and quota
4. Errors
5. Endpoints
6. Storefront HTTP API
7. Storefront JavaScript API
8. Events
9. Pixel events (Meta, GA4)
10. Klaviyo and Omnisend
11. Custom elements
12. Styling hooks
13. Versioning

REST API

A JSON API for your servers: an ERP, a CRM, a marketing tool or a headless storefront’s backend. It is on the Premium plan.

• Base URL: https://covewishlist.com/api/v1
• OpenAPI 3.1 document: /developers/openapi.json (import it into Postman, Insomnia or a code generator).
• JSON in and out. Every response carries Cache-Control: no-store.
• Customers are identified by their numeric Shopify customer ID only. The API never accepts or returns an email, name or any other customer detail, and a request body with a field it doesn’t know is refused.
• Every change is idempotent: saving an item twice, or removing something that isn’t saved, changes nothing. Retrying is always safe.
• IDs are strings in responses (JSON numbers can’t hold every 64-bit ID). In request bodies, product and variant IDs may be numeric strings, numbers or GIDs (gid://shopify/Product/…).

Authentication

Create a key in the app: Shopify admin › Apps › Cove Wishlist › Developers. Name it after what will use it and pick its access:

• Read: the GET endpoints.
• Read and write: also save and remove items.

The key is shown once, when you create it. We store only a one-way hash, so it can’t be shown again or recovered: if you lose it, revoke it and create another. Revoking takes effect at once. Keys are revoked automatically when the app is uninstalled. A shop can have up to 10 active keys.

Send the key as a bearer token:

curl https://covewishlist.com/api/v1/me \
  -H "Authorization: Bearer $COVE_API_KEY"

Keys work while the shop’s plan includes the developer API. After a downgrade, calls answer 403 plan_required until you upgrade again; the keys themselves are kept.

Rate limits and quota

• 120 requests per minute per key, and 600 per minute per shop across all its keys.
• Every response says where you are: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds).
• Over the limit: 429 rate_limited with a Retry-After header in seconds. Back off and retry.
• Repeated failed authentication from one IP address is also limited (30 a minute).
• Each new save through the API counts as one wishlist action toward the shop’s monthly quota, exactly like a save on the storefront. At the limit, adds answer 429 quota_reached; reads and removes keep working.

Errors

Errors are JSON, { "error": "code" }, with the HTTP status below. Match on the code, not the message.

Endpoints

GET/me

The shop and scope of the key. Use it to check credentials.

{ "shop": "your-store.myshopify.com", "scope": "READ_WRITE" }

GET/customers/{customerId}/wishlist

Every list of the customer with its saved items, newest first. A customer who never saved anything gets "lists": [], not a 404. List names are shopper text: show them as text, never as HTML. Share links and shoppers’ private notes are never returned; shared says whether a list has a live link.

curl https://covewishlist.com/api/v1/customers/7012345678901/wishlist \
  -H "Authorization: Bearer $COVE_API_KEY"

{
  "customerId": "7012345678901",
  "count": 2,
  "lists": [
    {
      "id": "clx0examplelistid0000",
      "name": "My wishlist",
      "isDefault": true,
      "shared": false,
      "createdAt": "2026-10-01T09:30:00.000Z",
      "count": 2,
      "items": [
        { "productId": "8123456789", "variantId": "45123456789", "quantity": 1, "addedAt": "2026-10-20T18:02:11.000Z" },
        { "productId": "8123456790", "variantId": null, "quantity": 1, "addedAt": "2026-10-02T10:00:00.000Z" }
      ]
    }
  ]
}

POST/customers/{customerId}/items

Save a product, or one variant of it, for a customer (read and write key). Without listId it goes to the customer’s default list, created on first use; with it, to that list, which must be one of theirs. Answers 201 with "added": true, or 200 with "added": false when it was already there, plus the new wishlist. A list holds up to 500 items.

curl -X POST https://covewishlist.com/api/v1/customers/7012345678901/items \
  -H "Authorization: Bearer $COVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "8123456789", "variantId": "45123456789" }'

DELETE/customers/{customerId}/items/{productId}

Remove a saved product (read and write key). Query parameters: variantId removes that variant’s save instead of the product-level one; listId removes it from that list only, otherwise it leaves every list. Answers { "removed": n, "wishlist": … }; removed is 0 when nothing was saved.

curl -X DELETE "https://covewishlist.com/api/v1/customers/7012345678901/items/8123456789?variantId=45123456789" \
  -H "Authorization: Bearer $COVE_API_KEY"

GET/products/most-saved

The shop’s products by how many shoppers have them saved now (a shopper counts once however many lists hold it), with saves, the saved rows. limit is 1 to 250, default 50. Counts only: never who saved.

{ "products": [{ "productId": "8123456789", "shoppers": 42, "saves": 47 }] }

Storefront HTTP API

The JSON endpoints the storefront hearts use, for custom wishlist UIs in an Online Store theme. They live under your store’s own domain at /apps/wishlist (Shopify’s app proxy), so they only work from your storefront: Shopify signs each request and passes the signed-in customer, if any. There is no key and nothing to configure. A headless storefront on another domain should call the REST API from its server instead.

• Every endpoint is POST with a JSON body and answers JSON (Cache-Control: no-store). Send Content-Type: application/json and credentials: "same-origin".
• Signed-in customers are recognised from Shopify’s signature. Guests get a random guestToken in the response to their first save: keep it (Cove’s own script uses localStorage key cove:guest, so share it to work alongside the hearts) and send it back in every body. It is the guest’s only credential: never put it in a URL. After sign-in, the next /state merges the guest list into the account.
• Limits: 60 writes a minute per shopper, 1200 requests a minute per shop.
• Errors use the same { "error": "code" } shape: sign_in_required (403, the store turned guest wishlists off), plan_required (403), not_signed_in (401), list_not_found / not_saved (404), list_full, list_limit, list_exists, last_list (409), rate_limited (429), paused (503).

The state most endpoints return (count is distinct saved products and variants; an item in two lists counts once):

{
  "signedIn": false,
  "count": 1,
  "items": [
    { "productId": "8123456789", "variantId": null, "listIds": ["clx0examplelistid0000"] }
  ],
  "lists": [{ "id": "clx0examplelistid0000", "name": "My wishlist", "isDefault": true }],
  "features": { "multipleLists": false, "sharing": true },
  "guestToken": "<only on a guest's first save>"
}

const res = await fetch('/apps/wishlist/items', {
  method: 'POST',
  credentials: 'same-origin',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'add',
    productId: '8123456789',
    guestToken: localStorage.getItem('cove:guest') || undefined,
  }),
});
const state = await res.json();
if (state.guestToken) localStorage.setItem('cove:guest', state.guestToken);

Two pages are served there too, as Liquid inside your theme: GET /apps/wishlist (the shopper’s wishlist) and GET /apps/wishlist/s/{token} (a shared list).

Storefront JavaScript API

On every storefront page with the Cove Wishlist app embed on, window.CoveWishlist works the hearts’ wishlist from your own theme code: the same calls, the same shopper (signed in or guest), and every heart and counter on the page updates with it. Nothing to install. The script loads deferred, so code that may run first can wait for the cove:ready event on document.

• Every method returns a promise. IDs are numeric Shopify IDs, as strings or numbers.
• Reads wait for the shopper’s wishlist to load, and cost no request at all for a shopper who has never saved anything.
• The API shows no toast or message: that is your UI’s job. Failures reject with an Error whose code is the storefront API’s error code (sign_in_required, rate_limited, list_full…). A missing or non-numeric product ID rejects with invalid_request without a request.

Events

cove:change fires on document after every save, removal and sync, from the hearts, the API or another component. event.detail is { items, count, action, productId }: action is add, remove or sync (the first load, a guest list merged at sign-in, a move between lists or a list change), and productId is the product saved or removed (null on a sync). On an add or removal it may also carry variantId, listId (absent for a one-tap save, which goes to the default list, or a removal from every list) and source. cove:ready fires once, when the script has set up.

document.addEventListener('cove:change', event => {
  const { count, action, productId } = event.detail;
  document.querySelector('#my-count').textContent = String(count);
});

const button = document.querySelector('#my-heart');
button.addEventListener('click', async () => {
  try {
    await window.CoveWishlist.toggle(button.dataset.productId);
  } catch (error) {
    if (error.code === 'sign_in_required') location.href = '/account/login';
  }
});

Pixel events (Meta, GA4)

On the Pro plan and up, Cove publishes wishlist actions as Shopify custom customer events. Any pixel on your store can subscribe to them: a custom pixel you add in Settings › Customer events, or an app pixel that listens for them. Shopify’s Facebook & Instagram and Google & YouTube apps send Shopify’s standard events only, so they don’t forward these on their own: the custom pixel below does. Like every pixel, they follow your store’s customer privacy settings.

source is one of:

• product_button: the product page button (or <cove-button>)
• card_heart: a heart on a product card
• list_sheet: the “Change” list picker after a save
• wishlist_page: the remove button on the wishlist page
• undo: Undo in the toast
• cart_save: Save for later on a cart line (the item then leaves the cart)
• api: your own code, through window.CoveWishlist

No event carries an email address, a customer ID, a guest token or a share link. Cove installs no pixel of its own: that would need permission to write your store’s pixel settings, and Cove asks for no write access to your store’s data.

Send wishlist saves to Meta and Google Analytics 4

1. In your Shopify admin, go to Settings › Customer events and click Add custom pixel. Name it “Cove Wishlist”.
2. Under Customer privacy, require Marketing and Analytics permission, as you would for any ads pixel.
3. Paste the code below, replace the Meta Pixel ID and GA4 measurement ID, then Save and Connect.
4. Save a product on your store, then check with the Meta Pixel Helper (AddToWishlist), GA4 DebugView (add_to_wishlist) or Shopify’s Test button on the pixel.

// Cove Wishlist → Meta Pixel and Google Analytics 4.
// Settings › Customer events › Add custom pixel. Paste this, replace the
// two IDs, and delete the half you don't use.
const META_PIXEL_ID = 'YOUR_META_PIXEL_ID';
const GA4_MEASUREMENT_ID = 'G-XXXXXXXXXX';

// Your catalog's ID for a saved item, so the event matches your ads catalog.
// Catalogs synced by Shopify's Facebook & Instagram and Google & YouTube
// apps usually use shopify_<COUNTRY>_<product ID>_<variant ID>: set your
// catalog's country, or return variantId if your catalog uses variant IDs.
const CATALOG_COUNTRY = 'US';
function catalogId(productId, variantId) {
  return variantId
    ? 'shopify_' + CATALOG_COUNTRY + '_' + productId + '_' + variantId
    : productId;
}

function loadScript(src) {
  const script = document.createElement('script');
  script.async = true;
  script.src = src;
  document.head.appendChild(script);
}

// Meta Pixel (Meta's base code, written out).
const fbq = (window.fbq = function () {
  fbq.callMethod ? fbq.callMethod.apply(fbq, arguments) : fbq.queue.push(arguments);
});
fbq.push = fbq;
fbq.loaded = true;
fbq.version = '2.0';
fbq.queue = [];
loadScript('https://connect.facebook.net/en_US/fbevents.js');
fbq('init', META_PIXEL_ID);

// Google tag. No page view: your Google channel already sends those.
window.dataLayer = window.dataLayer || [];
function gtag() {
  window.dataLayer.push(arguments);
}
loadScript('https://www.googletagmanager.com/gtag/js?id=' + GA4_MEASUREMENT_ID);
gtag('js', new Date());
gtag('config', GA4_MEASUREMENT_ID, { send_page_view: false });

analytics.subscribe('cove_item_added', (event) => {
  const { productId, variantId } = event.customData;
  const id = catalogId(productId, variantId);
  fbq('track', 'AddToWishlist', {
    content_ids: [id],
    content_type: 'product',
  });
  gtag('event', 'add_to_wishlist', {
    items: [{ item_id: id }],
  });
});

The same analytics.subscribe pattern works for the other events, for any service your pixel can reach.

Klaviyo and Omnisend

On the Pro plan and up, Cove can also hand wishlist saves, removals and back-in-stock signups to the Klaviyo or Omnisend script already on your store, so you can build flows on them. Turn each one on in the theme editor: App embeds › Cove Wishlist › Advanced › Send wishlist events to Klaviyo or Send wishlist events to Omnisend. Both are off until you do.

• Cove uses each platform’s documented onsite JavaScript (klaviyo.track, and Omnisend’s custom events) and only when that script is on the page. It never loads their scripts, and stores no Klaviyo or Omnisend API key.
• No event carries an email address or a customer ID. The platform attributes the event to the visitor it already recognises: Klaviyo tracks onsite events for browsers it has identified, and Omnisend for identified contacts. A visitor neither knows is not recorded.
• When your store collects consent with Shopify’s Customer Privacy API (Shopify’s cookie banner does), nothing is sent for a shopper who declined marketing.
• The product details come from the page: on a product page, the variant’s title, URL, image and price as your theme renders them; from a heart on a product card or the wishlist page, what that card shows, without a price. Nothing is fetched to fill them in.

Attentive isn’t supported: its onsite Tag SDK has no custom events, and its custom events API needs a private API key, which Cove doesn’t hold. Use Shopify Flow (below) instead.

Build a wishlist reminder flow in Klaviyo

1. Turn on Send wishlist events to Klaviyo and save a product on your store in a browser Klaviyo knows (for example after clicking one of your Klaviyo emails). Within a few minutes the profile’s activity feed shows Added to Wishlist.
2. In Klaviyo, create a flow from scratch and choose the metric Added to Wishlist as its trigger.
3. Add a flow filter such as “Placed Order zero times since starting this flow”, then a time delay (two or three days works for most stores).
4. Add an email. Use {{ event.ProductName }}, {{ event.ImageURL }}, {{ event.URL }} and {{ event.Price }}. For saves from a product card, which carry no price, look the product up in your synced catalog with Klaviyo’s catalog lookup tag on event.ProductID.

In Omnisend, the same works as an automation whose trigger is the custom event added product to wishlist; its properties are available to the email.

Back in stock, and the Shopify Flow alternative

A browser event can’t tell Klaviyo that a product came back in stock: Cove knows that on its server, from your inventory. On the Starter plan and up, Cove’s Shopify Flow triggers (Wishlisted item back in stock, price dropped, running low, item added) fire for signed-in customers, and Klaviyo’s Shopify Flow connector can turn one into a Klaviyo event:

1. In Shopify Flow, start a workflow with the Cove Wishlist trigger Wishlisted item back in stock.
2. Add Klaviyo’s Track an event action. Name the event (for example “Wishlist Item Back in Stock”), map the customer’s email and the product’s title, URL and image from the trigger. The Klaviyo public API key that action asks for is entered in Shopify Flow, not in Cove.
3. In Klaviyo, build a flow on that metric and send the email.

This works for any platform with a Shopify Flow action, and it reaches customers who saved while signed in, wherever they browse later. Cove can also send the back-in-stock email itself (Signed Up for Back in Stock then tells Klaviyo who asked).

Custom elements

For page builders and sections where the app’s blocks can’t go. Turn them on in the theme editor: App embeds › Cove Wishlist › Advanced › Load custom elements. Stores that leave it off load nothing extra.

• <cove-button product-id variant-id button-style>: a wishlist button for exactly that product (or variant), with the same design, toast, undo and list picker as the product button. button-style is icon-label (default), icon, text, pill or outline. Changing an attribute re-renders it.
• <cove-count>: the number of saved items, hidden at 0.
• <cove-link>: a link to the wishlist page with the count. Empty, it shows the design’s icon; anything inside it (text, your own icon) becomes the link’s content.

<cove-button product-id="8123456789"></cove-button>
<cove-button product-id="8123456789" variant-id="45123456789" button-style="icon"></cove-button>
<cove-count></cove-count>
<cove-link></cove-link>
<cove-link>My wishlist</cove-link>

The elements render text with textContent only and never fetch anything of their own.

Styling hooks

Restyle Cove from your theme’s CSS with these custom properties and classes. They are stable within version 1: we may add new ones, but renaming or removing one only happens in a new major version, announced here. Anything else about the markup (element order, wrappers, attributes not listed) can change in any release, so target the hooks, not the structure. Pro stores can also add custom CSS in the Design Studio.

Custom properties

Set by the app embed on :root from the Design Studio (the wishlist grid ones on .cove-wl). Override them in your theme to change one value everywhere.

States

Versioning

The REST API is versioned in its path (/api/v1) and follows semantic versioning: within v1 we only add (new endpoints, new optional fields, new error codes), so ignore fields you don’t know. Anything that would break an integration ships as /api/v2, announced here with time to move. The storefront endpoints, window.CoveWishlist, its events, the custom elements and the styling hooks follow the same rule (version 1).

Questions or a feature you need: contact@stackcraftdigital.co.uk. Security reports: see our security page.