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

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

string

required

Bearer token for authentication. Format: Bearer {your_api_key}.

string

required

Must be application/json.

Request body

string

required

A human-readable label for the watch. Used in webhook payloads and notification history responses.

string

required

The type of identifier you are using. One of "product", "asin", or "barcode".

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

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.

Show Rule object properties

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

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.

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.

object

The magnitude of change required to trigger the rule. Not required when condition is "change".

Show Threshold properties

string

required

Either "value" for an absolute value or "percentage" for a relative change. Availability and on_sale fields only support "value".

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.

object[]

required

Where to send alerts when a rule triggers.

Show Notification object properties

string

required

The delivery channel. Currently only "webhook" is supported.

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.

string

required

How quickly notifications are sent after a rule triggers. Currently only "immediately" is supported.

string

default:"active"

The initial status of the watch. Either "active" (starts checking immediately) or "paused" (created but not checking).

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.

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.

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.

object

Amazon Creator API credentials. Required for "asin" watches.

Show Networks object properties

string

required

Your Amazon Creator API credential ID.

string

required

Your Amazon Creator API credential secret.

string

required

Your Amazon Associates partner tag.

string

required

The Amazon marketplace locale, such as "US", "GB", or "DE".

Request examples

Product ID watch
ASIN watch
Barcode watch

Watch two products and trigger when the price drops by 10% or the item goes on sale.

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
  }'

Watch two Amazon ASINs and trigger when the price decreases by 50% from the provided start_value.

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"
      }
    }
  }'

Watch a single barcode across all merchants and trigger when the price drops by 10%.

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
  }'

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:

{
  "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.

{
  "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
    }
  ]
}

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.

Filters are not allowed for ASIN watches. Including a filters array in an ASIN watch request causes an error.

Account

Networks

Merchants

Products

Tools

Watches

Product Lists

Pools

Reports

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

Endpoint

Headers

Request body

Request examples

Webhook verification

Response

​Endpoint

​Headers

​Request body

​Request examples

​Webhook verification

​Response

Endpoint

Headers

Request body

Request examples

Webhook verification

Response