> ## 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.

# POST /v1/products/watches — create a product watch

> Create a product watch to receive webhook notifications when price, availability, or sale conditions change on the products you specify.

The `POST /v1/products/watches` endpoint creates a new product watch. You define the products to monitor, the rules that trigger a notification, the webhook URL to notify, and optional filters and metadata. The watch starts checking immediately after creation (unless you set `status: "paused"`).

## Endpoint

```
POST /v1/products/watches
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="name" type="string" required>
  A human-readable label for the watch. Used in webhook payloads and notification history responses.
</ParamField>

<ParamField body="target_type" type="string" required>
  The type of identifier you are using. One of `"product"`, `"asin"`, or `"barcode"`.
</ParamField>

<ParamField body="target_ids" type="string[]" required>
  The product identifiers to watch. For `"product"` watches, supply up to 100 Affiliate.com product IDs. For `"asin"` watches, supply up to 10 Amazon ASINs. For `"barcode"` watches, supply exactly 1 barcode (UPC, EAN, GTIN, or ISBN).
</ParamField>

<ParamField body="rules" type="object[]" required>
  The conditions that trigger a notification. When multiple rules are defined, **all rules must be met** (AND logic) for the watch to trigger. Maximum 10 rules for `product` and `asin` watches; exactly 1 rule for `barcode` watches.

  <Expandable title="Rule object properties">
    <ParamField body="rules[].field" type="string" required>
      The product attribute to watch. One of `"final_price"`, `"availability"`, `"on_sale"`, or `"sale_discount"`. Note: ASIN watches only support `"final_price"` and `"regular_price"`.
    </ParamField>

    <ParamField body="rules[].condition" type="string" required>
      How the field must change to trigger the rule. One of `"increase"`, `"decrease"`, `"equals"`, `"not_equals"`, `"greater_than"`, `"less_than"`, or `"change"`. Not all conditions are valid for every field — see the [overview](/api-reference/watches/overview#rule-types-and-conditions).
    </ParamField>

    <ParamField body="rules[].start_value" type="number">
      The baseline value at the time you create the watch. Required for all rules in ASIN watches. Optional for other watch types — if omitted, the API captures the current value on the first check.
    </ParamField>

    <ParamField body="rules[].threshold" type="object">
      The magnitude of change required to trigger the rule. Not required when `condition` is `"change"`.

      <Expandable title="Threshold properties">
        <ParamField body="rules[].threshold.type" type="string" required>
          Either `"value"` for an absolute value or `"percentage"` for a relative change. Availability and on\_sale fields only support `"value"`.
        </ParamField>

        <ParamField body="rules[].threshold.value" type="number | string | boolean" required>
          The threshold amount. For `"percentage"` type, supply a number from 1–100. For `"value"` type with `availability`, supply `"InStock"`, `"OutOfStock"`, or `"Unknown"`. For `on_sale`, supply `true` or `false`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="notifications" type="object[]" required>
  Where to send alerts when a rule triggers.

  <Expandable title="Notification object properties">
    <ParamField body="notifications[].channel" type="string" required>
      The delivery channel. Currently only `"webhook"` is supported.
    </ParamField>

    <ParamField body="notifications[].target" type="string" required>
      The webhook URL to POST the notification to. Must be a valid, publicly accessible HTTPS URL. The system sends a test request to this URL when the watch is created — your endpoint must return a `2xx` status or the watch creation will fail.
    </ParamField>

    <ParamField body="notifications[].frequency" type="string" required>
      How quickly notifications are sent after a rule triggers. Currently only `"immediately"` is supported.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="status" type="string" default="active">
  The initial status of the watch. Either `"active"` (starts checking immediately) or `"paused"` (created but not checking).
</ParamField>

<ParamField body="filters" type="object[]">
  Narrow which product listings trigger the watch. Each filter has a `field`, `operator`, and `value`. Supported fields: `network.id`, `merchant.id`, `direct_url`, `currency`. Multiple filters are combined with **AND** — all conditions must match. **Not allowed for ASIN watches.**
</ParamField>

<ParamField body="metadata" type="object">
  Up to 16 custom key-value pairs to attach to the watch. Keys are max 64 characters; values are max 512 characters. Returned in all API responses and in every webhook notification.
</ParamField>

<ParamField body="expire_timestamp" type="integer">
  UNIX timestamp when the watch should expire. Defaults to 90 days from creation. Maximum is 180 days from the current time. You receive a webhook notification when the watch expires.
</ParamField>

<ParamField body="networks" type="object">
  Amazon Creator API credentials. Required for `"asin"` watches.

  <Expandable title="Networks object properties">
    <ParamField body="networks.amazon.credential_id" type="string" required>
      Your Amazon Creator API credential ID.
    </ParamField>

    <ParamField body="networks.amazon.credential_secret" type="string" required>
      Your Amazon Creator API credential secret.
    </ParamField>

    <ParamField body="networks.amazon.partner_tag" type="string" required>
      Your Amazon Associates partner tag.
    </ParamField>

    <ParamField body="networks.amazon.locale" type="string" required>
      The Amazon marketplace locale, such as `"US"`, `"GB"`, or `"DE"`.
    </ParamField>
  </Expandable>
</ParamField>

## Request examples

<Tabs>
  <Tab title="Product ID watch">
    Watch two products and trigger when the price drops by 10% or the item goes on sale.

    ```bash theme={null}
    curl --request POST \
      --url 'https://api.affiliate.com/v1/products/watches' \
      --header 'Authorization: Bearer {your_api_key}' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Nike Shoe Price Drop Watch",
        "target_type": "product",
        "target_ids": [
          "9200-us-B01AFOIO3K",
          "8413578780281943353"
        ],
        "status": "active",
        "rules": [
          {
            "field": "final_price",
            "condition": "decrease",
            "start_value": 199.99,
            "threshold": {
              "type": "percentage",
              "value": 10
            }
          },
          {
            "field": "on_sale",
            "condition": "equals",
            "threshold": {
              "type": "value",
              "value": true
            }
          }
        ],
        "notifications": [
          {
            "channel": "webhook",
            "target": "https://example.com/webhooks/watch",
            "frequency": "immediately"
          }
        ],
        "filters": [
          {
            "field": "merchant.id",
            "operator": "=",
            "value": "41357"
          }
        ],
        "metadata": {
          "campaign": "summer_sale",
          "priority": "high"
        },
        "expire_timestamp": 1774751812
      }'
    ```
  </Tab>

  <Tab title="ASIN watch">
    Watch two Amazon ASINs and trigger when the price decreases by 50% from the provided `start_value`.

    ```bash theme={null}
    curl --request POST \
      --url 'https://api.affiliate.com/v1/products/watches' \
      --header 'Authorization: Bearer {your_api_key}' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Amazon Product Price Watch",
        "target_type": "asin",
        "target_ids": [
          "B01AFOIO3K",
          "B09J1TB35S"
        ],
        "status": "active",
        "rules": [
          {
            "field": "final_price",
            "condition": "decrease",
            "start_value": 123.99,
            "threshold": {
              "type": "percentage",
              "value": 50
            }
          }
        ],
        "notifications": [
          {
            "channel": "webhook",
            "target": "https://example.com/webhooks/watch",
            "frequency": "immediately"
          }
        ],
        "metadata": {
          "campaign": "amazon_deals"
        },
        "expire_timestamp": 1764822840,
        "networks": {
          "amazon": {
            "credential_id": "{your_credential_id}",
            "credential_secret": "{your_credential_secret}",
            "partner_tag": "{your_partner_tag}",
            "locale": "US"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Barcode watch">
    Watch a single barcode across all merchants and trigger when the price drops by 10%.

    ```bash theme={null}
    curl --request POST \
      --url 'https://api.affiliate.com/v1/products/watches' \
      --header 'Authorization: Bearer {your_api_key}' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Nike Shoe Barcode Price Drop Watch",
        "target_type": "barcode",
        "target_ids": [
          "6947681533400"
        ],
        "status": "active",
        "rules": [
          {
            "field": "final_price",
            "condition": "decrease",
            "threshold": {
              "type": "percentage",
              "value": 10
            }
          }
        ],
        "notifications": [
          {
            "channel": "webhook",
            "target": "https://example.com/webhooks/watch",
            "frequency": "immediately"
          }
        ],
        "filters": [
          {
            "field": "merchant.id",
            "operator": "=",
            "value": "138553"
          }
        ],
        "metadata": {
          "category": "footwear"
        },
        "expire_timestamp": 1764822840
      }'
    ```
  </Tab>
</Tabs>

## Webhook verification

When you create a watch with a `"webhook"` notification channel, the API immediately sends a test POST request to your endpoint to verify it is accessible. Your endpoint must return a `2xx` HTTP status code. If verification fails, the watch creation is rejected.

The test payload has the same structure as a real notification:

```json theme={null}
{
  "watch_history_id": "uuid-uuid-uuid-uuid",
  "watch_event_type": "product_watch_alert",
  "timestamp": "2026-01-02T19:18:50+00:00",
  "watch_id": "uuid-uuid-uuid-uuid",
  "watch_name": "Test Watch",
  "metadata": {
    "campaign": "summer_sale"
  },
  "details": [
    {
      "id": "abc-123456789",
      "network": {
        "id": 335,
        "name": "Impact US"
      },
      "merchant": {
        "id": 54419,
        "name": "Target"
      },
      "changes": [
        {
          "field": "final_price",
          "old_value": 199,
          "new_value": 149
        }
      ]
    }
  ]
}
```

## Response

A successful request returns `200 OK` with a list of all your active watches, including the one just created.

```json theme={null}
{
  "meta": {
    "total": 2,
    "from": 1,
    "to": 2,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "0195cedc-b193-7096-8df4-e7104abf799d"
  },
  "data": [
    {
      "watch_id": "9e84ce37-63be-41cf-87ef-72465fb8ead2",
      "name": "Nike Shoe Price Drop Watch",
      "target_type": "product",
      "target_id": "9200-us-B01AFOIO3K",
      "status": "active",
      "metadata": {
        "campaign": "summer_sale",
        "priority": "high"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": 199.99,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 10
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/webhooks/watch",
          "frequency": "immediately",
          "enabled": true
        }
      ],
      "filters": [
        {
          "field": "merchant.id",
          "operator": "=",
          "value": "41357"
        }
      ],
      "expire_timestamp": 1774751812
    }
  ]
}
```

<Warning>
  For ASIN watches, `start_value` is required for every rule. If you omit it, `start_value` will be `null` and the watch will never trigger — the API has no baseline to compare against.
</Warning>

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