> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/notify-me-and-coming-soon/api-custom-implementations.md).

# API custom implementations

The standard JavaScript widget is the recommended implementation when you want TWC to provide the customer-facing Notify Me / Coming Soon experience.

If you need a fully custom storefront experience, you can register customer interest directly using the TWC Customer Interest API.

## Authentication and customer identification

A custom frontend can register Notify Me or Coming Soon interest without requiring the shopper to log in or already exist in the retailer's customer database.

On Shopify, use the configured TWC app proxy to obtain the retailer's tenant-scoped TWC token. On other platforms, obtain and manage TWC REST API bearer tokens through your backend or integration service using credentials supplied by TWC.

Use the assigned tenant consistently for authentication and requests. Matching a submitted email must occur within that retailer tenant. A matching email associates the notification with the existing customer record; it does not authenticate the shopper or grant access to customer data.

## Endpoint

```http
POST https://api.au-aws.thewishlist.io/services/wsservice/api/wishlist/items/customerInterest
```

## Headers

```http
Content-Type: application/json
Authorization: Bearer <TWC token>
X-TWC-Tenant: <tenant_id>
```

{% hint style="warning" %}
Use the TWC authentication mechanism and tenant supplied for your implementation. Do not use Shopify Admin, TWC client or server credentials in browser-side code.
{% endhint %}

## Examples

{% tabs %}
{% tab title="Notify Me" %}

```json
{
  "email": "customer@example.com",
  "variantRef": "VAR_12345",
  "notifyMe": true,
  "comingSoon": false,
  "subscribe": false,
  "subscribeSms": false,
  "countryCode": "AU",
  "marketId": "123456789"
}
```

{% endtab %}

{% tab title="Coming Soon" %}

```json
{
  "email": "customer@example.com",
  "variantRef": "VAR_12345",
  "notifyMe": false,
  "comingSoon": true,
  "firstName": "Alex",
  "lastName": "Customer",
  "subscribe": true,
  "countryCode": "AU",
  "subscribeSms": false
}
```

{% endtab %}
{% endtabs %}

## Request fields

| Field          | Type    |    Required | Description                                                                                                        |
| -------------- | ------- | ----------: | ------------------------------------------------------------------------------------------------------------------ |
| `email`        | string  |   Mandatory | Customer email address. Must be a valid email format.                                                              |
| `variantRef`   | string  |         Yes | Retailer reference for the product variant.                                                                        |
| `mobile`       | string  | Conditional | Customer mobile number. Required when `subscribeSms` is `true`.                                                    |
| `firstName`    | string  |          No | Customer first name.                                                                                               |
| `lastName`     | string  |          No | Customer last name.                                                                                                |
| `subscribe`    | boolean |          No | Email/general marketing subscription flag. Defaults to `false`.                                                    |
| `notifyMe`     | boolean | Conditional | Registers the variant for a back-in-stock notification. At least one of `notifyMe` or `comingSoon` must be `true`. |
| `comingSoon`   | boolean | Conditional | Registers interest in a coming-soon/pre-launch variant. At least one of `notifyMe` or `comingSoon` must be `true`. |
| countryCode    | string  | Conditional | ISO 3166-1 alpha-2 country codes, such as AU, NZ, US and GB.  Required for Shopify Markets implementations         |
| `marketId`     | string  |          No | Shopify Market ID. A `gid://shopify/Market/...` value can be normalised to its numeric ID.                         |
| `subscribeSms` | boolean |          No | SMS marketing subscription flag. Defaults to `false`. If `true`, `mobile` is required.                             |
| `locationRef`  | string  |          No | Retailer/TWC location reference where applicable.                                                                  |
| `staffRef`     | string  |          No | Staff reference where applicable.                                                                                  |

## Validation rules

The current API requires:

* `email`
* `variantRef`
* At least one of `notifyMe` or `comingSoon` to be `true`

If `subscribeSms` is `true`, `mobile` must also be provided.

The standard widget sets either `notifyMe` or `comingSoon` according to its `data-type`. A custom implementation can use the API contract directly but should normally mirror that behaviour unless the business requirement is specifically to register both types of interest.

## Responses

<details>

<summary><code>200 OK</code></summary>

The customer interest record was created or updated successfully.

</details>

<details>

<summary><code>406 Not Acceptable</code></summary>

Used for validation failures such as:

* Missing email
* Missing variant reference
* Neither Notify Me nor Coming Soon being enabled

</details>

<details>

<summary><code>404 Not Found</code></summary>

May be returned for service-level validation/error cases in the current API, including attempting SMS subscription without a mobile number.

</details>

## Shopify Markets

For a Shopify Markets implementation, a countryCode must be passed with the wishlistItem.  Also pass the resolved Shopify Market ID as `marketId` where available.

If you are using the standard JavaScript widget, it can also collect storefront localization context such as country and province. See [Shopify Markets Support](broken://pages/2200f96f5cca5bff466ba75947d76efb24622607).

If you are building a custom API integration and require fields beyond the public API contract above, confirm those fields with TWC before implementation.