Triggers: How They Work and How to Use Them

A Trigger is a condition that decides when a Payout fires. When an order comes in on the Katalys network, each Trigger looks at that order (and the customer, click and event behind it) and answers one yes/no question: does this match? If every Trigger on a Payout answers yes, the Payout pays.

This page covers where Triggers fit, how to create one, a reference for every condition type, and a use-case cookbook with step-by-step recipes for the most common asks.

Where Triggers fit

Term → contains one or more Payouts → each Payout is gated by one or more Triggers

• Trigger — a condition on a Payout. It pays nothing on its own; it only decides whether its Payout is eligible.

• Payout — a single pay rule carrying a Payout dollar value (and a Commission value where allowed).

• Term — a reusable set of pay rules that can be applied to Partners, creating contracts.

• Contract — an agreement between a Partner and an Advertiser seting the rules of the relation

Two rules to remember

1. Within a Payout, Triggers combine with AND. If a Payout has several Triggers, all must match. Never OR.

2. Between Payouts, only the first match pays. Payouts are evaluated in priority order; the order pays the first Payout whose Triggers all match, and every later Payout is skipped. Put the most specific Payouts first and the Default Payout last.

Creating a Trigger

Creating a Trigger is a three-step wizard:

Once saved, add the Trigger to a Payout inside a Term, then apply the Term to Contracts.

Naming tip: name Triggers after what they match, not what they pay — "New customers only", "SKU = GLP1", "Within 7 days of click". Avoid names like "Recurring" or "Existing" that describe a payout outcome; they become misleading when the Trigger is reused.

Which condition answers my question?

Before you build

Use this checklist whether you are setting up a Trigger for your own program or configuring one with a Katalys partner:

• Confirm that the integration sends the fields required by the Trigger.

• Use the exact SKU, coupon-code, action-type, and click-property values reported by the integration.

• Decide how orders with missing or unknown customer data should be handled.

• Put specific Payouts before broader Payouts and keep the Default Payout last.

• Test overlapping conditions, multi-item orders, and expected Default Payout behavior before applying the Term to Contracts.

Integration data requirements

Triggers can only match data Katalys receives. Confirm the fields below before creating a Trigger, and use values exactly as the integration reports them.

Condition reference

Every condition's Configure step has a View Documentation link back to this page. Conditions that depend on specific integration fields show a yellow warning on that step — check with the advertiser that those fields are being sent before building.

Action Type

What it does: Matches the Action Type reported by the Advertiser's integration (for example a purchase vs. a subscription renewal vs. a lead/sign-up).

When to use it: When the advertiser reports more than one kind of conversion and each should pay differently.

Configure:

• Operator — defaults to Exact Match.

• Value (required) — the action type exactly as the advertiser's integration reports it.

Example: A subscription brand reports purchase and renewal. Payout A ($80) uses Action Type = purchase; Payout B ($10) uses Action Type = renewal.

Click Property

What it does: Matches a sub-property of the click associated with the conversion — how the customer arrived.

When to use it: To pay differently by a source or value passed in a publisher sub-property, placement or campaign.

Configure:

• Click Property Field — which click property to check (e.g. Sub1).

• Match Type — how the value is compared.

• Value (required) — the value to look for.

Example: A partner passes sub1=newsletter on email traffic. A $50 Payout is gated by Click Property: Click Property Field = Sub1, Value = newsletter. All other clicks fall to the Default Payout.

Coupon Code

What it does: Selects conversions where certain coupon codes were reported.

When to use it: Influencer/creator deals where a code identifies the partner, or to treat promo-driven orders differently.

Configure:

• Operator — how the codes are matched.

• Value (required) — one or more codes. Use * as a wildcard: blackfriday* matches every code starting with "blackfriday".

Example: An influencer is given SAVE20. A $25 Payout is gated by Coupon Code = SAVE20, so they're credited only when their code is used. For a family of codes (SAVE20, SAVE20VIP…), use SAVE20*.

Customer History

What it does: Selects customers who are new to the brand or returning. Requires: the integration to send email_address and order_count.

When to use it: New-customer acquisition bounties, or a separate (usually lower or $0) rate for existing customers.

Configure:

• Operator — Match First Time Customers or Match Returning Customers.

• Days Since Last Order (optional) — narrows the match by how many days have passed since the customer's previous order.

• Match Unknown Customers — whether orders with no email_address reported should be included. Default: Skip them.

Example: A $100 Payout is gated by Customer History = Match First Time Customers. A returning customer's order doesn't match, so the bounty is reserved for true new acquisitions. Watch out: if the advertiser doesn't reliably send email_address, decide deliberately whether unknown customers should match — with the default (skip), those orders won't match this Trigger at all.

Event Age

What it does: Matches an age range, in days, between the action (e.g. the click) and the conversion.

When to use it: Pay the full rate only for conversions that happen soon after the click, or taper the payout for late conversions.

Configure:

• Minimum Days — leave empty for No minimum.

• Maximum Days — leave empty for No maximum.

• Both accept 0–365.

Example: Payout A ($60) uses Event Age Minimum Days 0 / Maximum Days 7; Payout B ($30) uses Minimum Days 8 / Maximum Days 30. A customer who buys 12 days after clicking gets Payout B.

Line Item

What it does: Matches a line-item property reported by the Advertiser's integration — typically SKU. Requires: the integration to send line_item_* fields.

When to use it: When the payout should depend on what was bought.

Configure:

• Operator — what to match on (e.g. Match SKUs).

• Type — Include (the order contains the value) or Exclude (the order does not contain it).

• Value (required) — supports * as a wildcard (e.g. GLP1* matches every SKU starting with "GLP1").

Example: A telehealth advertiser pays $80 when an order contains SKU GLP1 and $50 when it contains NAD+ — one Line Item Trigger per Payout (Operator Match SKUs, Type Include).

Nth Conversion

What it does: Selects the first, second, etc. conversion linked to the same click, coupon or customer.

When to use it: Paying only once per customer or click, or paying a lower rate on repeat conversions.

Configure:

• Correlation Mode — what conversions are counted against: Per Click (default), or Per Customer. Per Customer requires email_address in the integration.

• Minimum number / Maximum number — which conversions match. Counting starts at 1 (1 = first conversion, 2 = second…). Leave empty for No minimum / No maximum.

Example: Per Customer, Minimum = 2, Maximum blank. Matches every conversion after a customer's first — use it on a lower repeat-purchase Payout.

Customer History vs. Nth Conversion: Customer History asks "is this person new to the brand?" Nth Conversion asks "how many times has this click / coupon / customer converted through Katalys?" A long-time brand customer can still be on their first Katalys conversion.

Order Value

What it does: Selects conversions with a high or low subtotal.

When to use it: Threshold incentives — more for bigger baskets, or nothing below a minimum.

Configure:

• Operator — e.g. Is greater than.

• Value (required) — the amount in $.

Example: A $60 Payout is gated by Order Value (subtotal) greater than $200. Smaller orders fall through to a lower Payout.

Use-case cookbook

Every recipe ends the same way: add the Trigger to a Payout in a Term → set the payout → order the Payouts → apply the Term to Contracts.

Convert only new customers

1. Create a Customer History Trigger.

2. Operator = Match First Time Customers. Leave Match Unknown Customers on Skip them unless orders without an email should also pay.

3. Add it to the Term's Payout and set the payout.

4. Apply the Term to Contracts.

Pay a lower commission on someone's 2nd+ conversion

1. Create an Nth Conversion Trigger.

2. Correlation Mode = Per Customer (requires email_address in the integration).

3. Minimum number = 2, Maximum number empty.

4. Add it to a Payout with the lower amount, ranked above the Default Payout.

5. Apply the Term to Contracts.

Pay each customer only once (new and existing to the brand)

1. Create an Nth Conversion Trigger.

2. Correlation Mode = Per Customer.

3. Minimum number = 1, Maximum number = 1 (first Katalys conversion only).

4. Add it to a Payout and set the payout. Make sure the Default Payout does not pay on later conversions.

5. Apply the Term to Contracts.

Pay once per click (ignore duplicate conversions from the same click)

1. Create an Nth Conversion Trigger.

2. Correlation Mode = Per Click, Minimum number = 1, Maximum number = 1.

3. Add it to the paying Payout and apply the Term.

Pay more for a specific product

1. Create a Line Item Trigger: Operator Match SKUs, Type Include, Value = the SKU (e.g. GLP1).

2. Add it to a higher-value Payout ranked above the default Payout.

3. Apply the Term to Contracts.

Pay a different amount when a coupon code is used

1. Create a Coupon Code Trigger with the code or codes as the Value (use * for a family of codes, such as SAVE20*).

2. Add the Trigger to the Payout whose amount should apply when that code is used.

Bonus on high-value orders

1. Create an Order Value Trigger: Operator Is greater than, Value = the threshold.

2. Add it to the bonus Payout, ranked above the Default Payout.

Pay on subscription renewals

1. Create an Action Type Trigger: Operator Exact Match, Value = the renewal action type as the advertiser reports it.

2. Add it to a (usually smaller) renewal Payout.

3. Keep a separate Payout for the initial purchase.

Full rate only for quick conversions

1. Create an Event Age Trigger: Minimum Days 0, Maximum Days 7 (or the agreed window).

2. Add it to the full-rate Payout; add a second Event Age Trigger (Minimum Days 8, Maximum Days 30) on a lower Payout if late conversions should still pay something.

Different rate per source or publisher sub-property

1. Create a Click Property Trigger: Click Property Field = Sub1, set the Match Type, Value = newsletter.

2. Add it to the Payout for that source, ranked above the Default Payout.

3. After issuing the tracking link, confirm that the publisher is sending the expected value in the selected sub-property

Combine conditions: new customer + specific product + minimum order

Pay $120 only when a new customer buys GLP1 on an order over $150:

1. One Payout, three Triggers: Customer History (Match First Time Customers) + Line Item (Match SKUs, Include, GLP1) + Order Value (Is greater than $150).

2. All three must match. If you want either condition to pay, create two Payouts instead.

Don't pay when an order contains a specific product

1. Create a Line Item Trigger: Operator Match SKUs, Type Exclude, Value = the SKU (wildcards allowed).

2. Add it to the paying Payout(s) — they'll only fire when that SKU is not in the order.

Worked example: Telehealth Term

Term: "Telehealth – Base"

How overlapping products resolve: If an order contains both GLP1 and NAD+, both product-specific Triggers can match, but only the first matching Payout pays. This is first-match-only behavior, not an additive payout; the GLP1 Payout wins because it is ranked first.

The Term is applied to many partners as Contracts. Individual Contracts (e.g. Forbes, WebMD) can carry partner-specific overrides while the base logic stays reusable.

Best practices and common pitfalls

• Specific first, Default Payout last. Precedence is first-match-only, so rank Payouts from most specific to least, and highest amount to lowest when tiers overlap.

• AND, not OR. Multiple Triggers on one Payout must all match. Split alternatives across Payouts.

• Don't mix up the customer conditions. Customer History = new vs. returning to the brand. Nth Conversion = conversion count through Katalys per click, coupon or customer.

• Triggers only see what the integration sends. Line Item needs line_item_* fields; Customer History and Nth Conversion Per Customer need email_address; Action Type needs the action type. The Configure step warns you — check with the advertiser before building.

• Use wildcards for code and SKU families. blackfriday* or GLP1* saves maintaining long lists.

• Name Triggers by what they match, not what they pay.

• Triggers in use can't be deleted. A Trigger used by an active Contract generally can't be removed. Plan for reuse.