> ## Documentation Index
> Fetch the complete documentation index at: https://guides.affiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Watch API: monitor price and availability

> Monitor affiliate products for price drops, availability changes, and sale events, and receive webhook notifications when your conditions are met.

The Product Watch API lets you monitor affiliate products for price changes, availability updates, and sale events. When a condition you define is met, the API sends a notification to your webhook. You define the products to watch, the rules that trigger a notification, and how long the watch remains active.

## Watch types

Choose the watch type that matches how you identify your products.

<Tabs>
  <Tab title="Product ID">
    Use `target_type: "product"` to watch products using internal Affiliate.com product IDs. This is the most flexible watch type and supports every rule, filter, and condition.

    **Limits**

    * Up to 100 product IDs per watch
    * Up to 10 rules per watch

    **Supported filters**: `network.id`, `merchant.id`, `direct_url`, `currency`

    Use this type when you have already searched for and identified products in the Affiliate.com database.
  </Tab>

  <Tab title="ASIN">
    Use `target_type: "asin"` to monitor Amazon products directly by their ASIN, without first searching the Affiliate.com database.

    **Limits**

    * Up to 10 ASINs per watch
    * Up to 10 rules per watch
    * Only `final_price` and `regular_price` rules are supported
    * Filters are **not** allowed

    **Requirements**

    * You must include Amazon Creator API credentials in the `networks` object (`credential_id`, `credential_secret`, `partner_tag`, `locale`)
    * `start_value` is required for every rule — without it, the watch will never trigger
  </Tab>

  <Tab title="Barcode">
    Use `target_type: "barcode"` to monitor a product across all merchants using its universal product code (UPC, EAN, GTIN, or ISBN).

    **Limits**

    * Exactly 1 barcode per watch
    * Exactly 1 rule per watch

    **Supported filters**: `network.id`, `merchant.id`, `direct_url`, `currency`

    This type is ideal for cross-merchant price comparison — you track a single product code and receive alerts regardless of which retailer changes their price first.
  </Tab>
</Tabs>

## Watch behavior

Watches are checked **every 6 hours**. When a rule condition is satisfied during a check, the watch transitions to `"completed"` status and a notification is sent to your webhook.

Completed watches do **not** resume automatically. To continue monitoring after a rule triggers, call the PUT endpoint and set `status: "active"` with updated rules or a new `expire_timestamp`.

If a watched product becomes unavailable in the database, the watch is removed and you receive a final notification with `field: "__product__"` and `new_value: "unavailable"`.

## Expiration policy

Every watch expires at a configurable timestamp.

| Setting            | Value                          |
| ------------------ | ------------------------------ |
| Default expiration | 90 days from creation          |
| Maximum expiration | 180 days from the current time |

If you do not supply `expire_timestamp`, the watch expires 90 days from when you create it. When a watch reaches its expiration, you receive a webhook notification and the watch stops checking.

## Metadata

You can attach up to **16 key-value pairs** of custom metadata to each watch. Use metadata to tag watches with campaign names, product categories, priority levels, or any other context your application needs.

* Key maximum length: 64 characters
* Value maximum length: 512 characters

Metadata is returned in all API responses and in every webhook notification, so you can use it to route and process notifications programmatically. You can also filter watches by metadata using query parameters: `?metadata[campaign]=summer_sale`.

## Rule types and conditions

Rules define what change triggers a notification. Each rule specifies a `field` (what to watch), a `condition` (how it must change), and optionally a `threshold` (by how much).  Multiple rules all must match to trigger a notification (logical AND).

### Supported conditions by field

| Field           | change | equals | not\_equals | increase | decrease | greater\_than | less\_than |
| --------------- | ------ | ------ | ----------- | -------- | -------- | ------------- | ---------- |
| `availability`  | ✓      | ✓      | ✓           | —        | —        | —             | —          |
| `on_sale`       | ✓      | ✓      | ✓           | —        | —        | —             | —          |
| `sale_discount` | ✓      | ✓      | ✓           | ✓        | ✓        | ✓             | ✓          |
| `final_price`   | ✓      | ✓      | ✓           | ✓        | ✓        | ✓             | ✓          |

The `change` condition triggers on any change and does not require a threshold. All other conditions require a threshold.

### Threshold types

| Field           | `value` | `percentage` |
| --------------- | ------- | ------------ |
| `availability`  | ✓       | —            |
| `on_sale`       | ✓       | —            |
| `sale_discount` | ✓       | ✓            |
| `final_price`   | ✓       | ✓            |

**Allowed threshold values when `threshold.type` is `"value"`:**

| Field           | Allowed values                           |
| --------------- | ---------------------------------------- |
| `availability`  | `"InStock"`, `"OutOfStock"`, `"Unknown"` |
| `on_sale`       | `true`, `false`                          |
| `sale_discount` | Numeric float, 0–100                     |
| `final_price`   | Numeric, greater than 0                  |

**When `threshold.type` is `"percentage"`**: provide a number from 1–100.

## Filters

You can optionally narrow which products trigger a watch using the `filters` array. Each filter specifies a `field`, an `operator`, and a `value`.

Supported filter fields: `network.id`, `merchant.id`, `direct_url`, `currency`

```json theme={null}
{
  "filters": [
    {
      "field": "merchant.id",
      "operator": "=",
      "value": "41357"
    },
    {
      "field": "currency",
      "operator": "=",
      "value": "USD"
    }
  ]
}
```

<Warning>
  Filters are not supported for ASIN watches. Including a `filters` array in an ASIN watch request will result in an error.
</Warning>

## Available endpoints

| Method   | Endpoint                                    | Description                                    |
| -------- | ------------------------------------------- | ---------------------------------------------- |
| `GET`    | `/v1/products/watches`                      | List all your product watches.                 |
| `POST`   | `/v1/products/watches`                      | Create a new product watch.                    |
| `GET`    | `/v1/products/watches/{watch_id}`           | Retrieve a specific watch by ID.               |
| `PUT`    | `/v1/products/watches/{watch_id}`           | Update or reactivate a watch.                  |
| `DELETE` | `/v1/products/watches/{watch_id}`           | Delete a watch.                                |
| `GET`    | `/v1/products/watches/{watch_id}/histories` | Get notification history for a specific watch. |
| `GET`    | `/v1/products/watches/histories`            | Get notification history filtered by metadata. |