Visibility rules

A visibility rule is a server-evaluated condition that controls whether a given deal is shown. Rules attach to a deal and combine partner-level dimensions (partner and partner type) with per-member dimensions (the user’s type(s) and region(s)). Where each dimension applies depends on the endpoint: the partner-scoped catalogue listing (GET /v1/deals) evaluates only the partner-level dimensions, it has no end user in scope, while the per-member dimensions are enforced where a member is in scope, namely the hosted end-user listing and GET /v1/deals/{id}/instructions.

Request shape

Every create call uses the same body:

{
  "deal_id": "018e4b2a-0000-7def-abcd-000000000010",
  "rule_type": "include_region",
  "rule_value": ["Europe", "North America"],
  "priority": 0
}

Field	Type	Required	Notes
`deal_id`	uuid	No	The deal the rule applies to. Taken from the `{deal_id}` path segment; a `deal_id` in the body is ignored, so you can omit it
`rule_type`	enum	Yes	One of the include/exclude variants below
`rule_value`	array of string	Yes	Operand values, semantics depend on `rule_type`
`priority`	integer	No	Evaluation order (default `0`)

Common patterns

Region-locked deal

Only show this deal to users in Europe or North America:

curl -X POST https://perks.founderpass.com/v1/portal/deals/{deal_id}/visibility-rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deal_id": "{deal_id}",
    "rule_type": "include_region",
    "rule_value": ["Europe", "North America"],
    "priority": 0
  }'

Hide a deal from a specific user type

Block the deal for users tagged “Idea stage”:

{
  "deal_id": "{deal_id}",
  "rule_type": "exclude_user_type",
  "rule_value": ["Idea stage"],
  "priority": 0
}

Allow only certain partner types

Useful when configuring a global deal that should only reach accelerators and incubators:

{
  "deal_id": "{deal_id}",
  "rule_type": "include_partner_type",
  "rule_value": ["Accelerator", "Incubator"],
  "priority": 0
}

Updating and deleting rules

# Update, body is partial; send any of rule_type, rule_value, priority (only the fields you want to change)
curl -X PATCH https://perks.founderpass.com/v1/portal/visibility-rules/{rule_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rule_value": ["Europe"], "priority": 1 }'

# Delete
curl -X DELETE https://perks.founderpass.com/v1/portal/visibility-rules/{rule_id} \
  -H "Authorization: Bearer $TOKEN"

Rule types

All rule types follow the same include_* / exclude_* pattern. Include means “only these”; exclude means “everyone except these”.

`rule_type`	`rule_value` contains	Behaviour
`include_partner`	Partner UUIDs	Show only to listed partners
`exclude_partner`	Partner UUIDs	Hide from listed partners
`include_partner_type`	`PartnerType` values	Show only to these partner types
`exclude_partner_type`	`PartnerType` values	Hide from these partner types
`include_region`	`AudienceRegion` values	Show only in listed regions
`exclude_region`	`AudienceRegion` values	Hide from listed regions
`include_user_type`	`UserType` values	Show only to these user types
`exclude_user_type`	`UserType` values	Hide from these user types

How rules combine

Evaluation pools every rule on the deal into two gates:

Include gate: if the deal has any include_* rule, the subject must match at least one of them. Include rules OR together, even across different dimensions, so a deal carrying both include_partner_type and include_region is shown to a subject that matches either one, not only one that matches both. A deal with no include rules clears this gate automatically.
Exclude gate: any single exclude_* match hides the deal.

A deal is visible when it clears both gates: (no include rules, or matches at least one include rule) AND matches no exclude rule.

To express OR within one dimension (e.g. “Europe or North America”), put both values in a single rule’s rule_value array, the entries in one rule_value also OR together.

Toggling a global deal on or off

If you just want to hide a global FounderPass deal from your portal without writing a rule, use the per-deal visibility toggle:

curl -X PATCH https://perks.founderpass.com/v1/portal/deals/{deal_id}/visibility \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "visible": false }'

See the API Reference for the full response schemas.

`api_excluded` vs other controls

Three different mechanisms can keep a deal out of a listing. They operate at different scopes, don’t confuse them:

Control	Who sets it	Scope	Effect
Visibility rules	Partner (this guide)	Per-deal, per-segment	Gate a deal by partner, partner type, region, or user type
Visibility toggle (`partner_deal_visibility`)	Partner	Per-deal, per-partner	Hide a single global deal from your portal, affects both the hosted app and the Partner API
`api_excluded`	FounderPass super_admin	Per-deal, channel-scoped	Removes the deal from the Partner API only (`GET /v1/deals`, detail, instructions, attributed tracking), while it stays live in the hosted app
`hidden_globally`	FounderPass super_admin	Per-deal, everywhere	Pulls the deal from every channel for every partner

The key distinction: api_excluded is channel-scoped, not partner-scoped. A deal marked api_excluded never appears on any Partner API path for any partner, yet end users still see and claim it in the hosted storefront. You can’t change api_excluded yourself, it’s an admin-side flag, but you’ll see it reflected as the deal simply being absent from your API responses. The api_excluded boolean is surfaced on the Deal model for reference.