> For the complete documentation index, see [llms.txt](https://wishlist.nativeappco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wishlist.nativeappco.com/integrations/wishlist-api.md).

# Wishlist API

Read and change a signed-in customer's wishlists from a mobile app or a headless storefront

{% hint style="info" %}
**Need help?** [Contact Us](mailto:undefined) or [Book a Meeting](https://calendly.com/nativeappco-support/30min) with us
{% endhint %}

The Wishlist API lets a client outside your Shopify theme, such as a mobile app or a headless storefront, show and change the wishlists of the customer who is signed in there. It works with the same wishlists as your online store, so a product saved in the app shows up on the website and the other way round.

Saves made through the API count in your stats and reports and trigger your [Shopify Flow](https://wishlist.nativeappco.com/shopify-flow.md) workflows, including the Klaviyo ones.

## Requirements

* Fish Wishlist on a **paid plan**.
* **New customer accounts** in Shopify (**Settings → Customer accounts**). Legacy customer accounts are not supported.
* A client that signs customers in with Shopify and holds their **Customer Account API access token**.

## Enable the API

The API is off until you switch it on.

1. In Fish Wishlist, open **Developer tools → API**.
2. Tick **Allow access to this store's wishlists through the API** and save.

The same screen shows your endpoint. Switching the API off blocks all requests within a minute.

## How access works

* Every request carries the access token of a signed-in customer. Fish Wishlist asks Shopify who the token belongs to, and the request can only reach that customer's own wishlists.
* There is no API key and no way to read another customer's wishlists.
* A token from another store is refused.
* Guests can't use the API. Ask the customer to sign in first.

{% hint style="warning" %}
The customer's access token is a credential. Send it only to the Fish Wishlist endpoint, over HTTPS, and never write it to logs.
{% endhint %}

## Request

```
POST https://fish.nativeappco.com/api/v1/wishlist
Authorization: Bearer <customer access token>
Content-Type: application/json
```

| Field        | Required        | Description                                                                            |
| ------------ | --------------- | -------------------------------------------------------------------------------------- |
| `shop`       | Always          | Your store's `.myshopify.com` domain, for example `your-store.myshopify.com`.          |
| `action`     | Always          | `ids`, `list`, `add` or `remove`.                                                      |
| `variantId`  | `add`, `remove` | Numeric ID of the product variant.                                                     |
| `wishlistId` | `remove`        | ID of the wishlist (`WL1` to `WL10`). Optional for `add`.                              |
| `country`    | No              | Two-letter country code (`AU`, `US`). `list` then returns that market's prices.        |
| `client`     | No              | A short name for your app (`tapcart`, `my-app`), kept with the activity for reporting. |

## Actions

### `ids`: which products are saved

The fastest call. Use it to fill the hearts on product and collection screens.

```json
{ "shop": "your-store.myshopify.com", "action": "ids" }
```

```json
{
  "ok": true,
  "lists": [
    { "id": "WL1", "name": "My wishlist", "variantIds": [44012345678901, 44012345678902] }
  ]
}
```

### `list`: wishlists with product details

Use it for the wishlist screen. Products that were deleted or are no longer active are left out.

```json
{ "shop": "your-store.myshopify.com", "action": "list", "country": "AU" }
```

```json
{
  "ok": true,
  "lists": [
    {
      "id": "WL1",
      "name": "My wishlist",
      "items": [
        {
          "variantId": 44012345678901,
          "productId": 8123456789012,
          "handle": "linen-shirt",
          "title": "Linen Shirt",
          "variantTitle": "Blue / M",
          "image": "https://cdn.shopify.com/...",
          "price": "89.95",
          "compareAtPrice": "119.95",
          "currency": "AUD",
          "available": true
        }
      ]
    }
  ]
}
```

### `add`: save a product

Without `wishlistId` the product goes to the customer's first wishlist. A customer with no wishlist yet gets one, named with your store's default wishlist title.

```json
{ "shop": "your-store.myshopify.com", "action": "add", "variantId": 44012345678901 }
```

```json
{ "ok": true, "wishlistId": "WL1", "wishlistName": "My wishlist" }
```

If the product was already in the list, the response also has `"alreadySaved": true`.

### `remove`: remove a product

```json
{ "shop": "your-store.myshopify.com", "action": "remove", "variantId": 44012345678901, "wishlistId": "WL1" }
```

```json
{ "ok": true }
```

## Errors

A refused request answers with `"ok": false` and a `reason`.

| Status | Reason                    | What it means                                                               |
| ------ | ------------------------- | --------------------------------------------------------------------------- |
| 400    | `bad_request`             | A field is missing or has the wrong format.                                 |
| 401    | `not_logged_in`           | The token is missing, expired or not from this store. Sign the customer in. |
| 403    | `api_disabled`            | The API is switched off for this store, or the store isn't on a paid plan.  |
| 422    | `invalid_variant`         | The store has no variant with this ID.                                      |
| 422    | `invalid_list`            | `wishlistId` is missing for `remove`.                                       |
| 422    | `list_full`               | The wishlist already holds 128 products.                                    |
| 422    | `no_free_slot`            | The customer already has the maximum number of wishlists.                   |
| 422    | `free_plan_limit_reached` | The store reached its plan's customer limit.                                |
| 429    | `rate_limited`            | Too many requests. Wait a minute and try again.                             |
| 500    | `failed`                  | Something went wrong on our side. Try again.                                |

## Limits

* A customer can make 30 changes (`add`, `remove`) per minute.
* Call `ids` once per screen and reuse the result for every heart on it, rather than once per product.
