Listing deals

GET /v1/deals returns the deals available to your partner account, the global FounderPass catalog plus any live partner-private deals you’ve created, with every partner-level visibility rule applied (global rules, partner/partner-type targeting, channel exclusion, and your per-deal toggles). It is partner-scoped: it does not take an end user, so it never applies per-member region, user-type, or eligibility gates. Those are enforced per member at GET /v1/deals/{id}/instructions (and on the hosted end-user listing).

A simple call

curl "https://perks.founderpass.com/v1/deals?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Narrowing the listing

Pass query parameters to narrow the listing.

curl "https://perks.founderpass.com/v1/deals?\
tier=premium&\
category=cloud-infrastructure" \
  -H "Authorization: Bearer $TOKEN"

Parameter	Type	Notes
`category`	string	Category slug, see `GET /v1/categories`
`tier`	enum	`free` or `premium`, filters by the deal’s tier
`page`, `per_page`	integer	Standard pagination (`per_page` max `100`)

There’s no region or user_type parameter: this endpoint is partner-scoped (see above). To narrow by region, read each deal’s available_regions and filter client-side (see the tip below).

Eligibility criteria on each deal

List and detail responses include the deal’s eligibility so you can display requirements or filter on your side:

eligibility_requirements, a human-readable string (e.g. “Must be a VC-backed company founded in the last 5 years”). Render it on the deal card or detail page.
Structured arrays for programmatic checks, empty means “no constraint on this dimension”:

Field	Example values
`eligibility_customer_type`	`new_customers_only`, `existing_customers_eligible`
`eligibility_company_stage`	`pre_seed`, `seed`, `series_a_plus`, `smb`, `enterprise`, `any`
`eligibility_company_size`	`1_10`, `11_50`, `51_200`, `200_plus`
`eligibility_business_type`	`startup`, `agency`, `ecommerce`, `saas`, `creator`, `local_business`, `any`
`eligibility_geography`	ISO-3166-1 alpha-2 country codes: e.g. `US`, `DE`, `GB` (uppercase). Not `AudienceRegion` names, those apply only to `regions` / visibility rules, not to eligibility.
`eligibility_incorporation`	`registered_company_required`, `sole_traders_allowed`
`eligibility_funding`	`vc_backed_only`, `accelerator_only`, `student_founders`, `coworking_members`, `portfolio_companies_only`

These are informational on the Partner API, surface them to set expectations, but the offering partner still performs the actual eligibility check at redemption.

Fetching a single deal

curl "https://perks.founderpass.com/v1/deals/{id}?user_tier=premium" \
  -H "Authorization: Bearer $TOKEN"

Returns the full deal object. Optional user_tier query param enforces tier gating, if the user is free and the deal is premium, you’ll get a 403 with reason: "tier_upgrade_required" and upgrade_required: true.

Getting redemption instructions

When a user clicks “Claim”, fetch their redemption details. As a side effect the endpoint emits a deal.instructions_viewed webhook and records a deal_redeemed analytics event for that user, once per (partner, user, deal), so you don’t track redemptions on the API path yourself. Both side effects are best-effort (a failure never fails the read), and neither fires for a coming_soon deal (that path returns 409 with no redemption assets).

curl "https://perks.founderpass.com/v1/deals/{id}/instructions?user_id={user_uuid}" \
  -H "Authorization: Bearer $TOKEN"

user_id is required as a query parameter, the server checks that user’s tier against the deal’s tier and returns 403 with reason: "tier_upgrade_required" and upgrade_required: true if they don’t qualify.

Status codes to handle

403 { "reason": "tier_upgrade_required", "upgrade_required": true }, the user’s tier is below the deal’s.
404, the deal isn’t redeemable for this user. The body tells you why for the gates you can act on:
- { "reason": "region_restricted" }, the member’s regions don’t satisfy the deal’s region targeting: either they include a region the deal excludes, or they’re absent from the deal’s include-region list. Sync the member’s actual region.
- { "reason": "user_type_restricted" }, the deal is limited to certain user types the member isn’t in.
- { "reason": "eligibility_mismatch", "dimension": "eligibility_company_stage" }, the member’s eligibility doesn’t overlap the deal on the named dimension. Set that dimension on the member.
- No reason (bare { "error": ... }), the deal isn’t available to your account (hidden, api_excluded, or not in your catalogue); nothing to fix at the member level.
409 { "deal_status": "coming_soon" }, the deal is announced but not yet redeemable; its redemption assets are withheld. Treat this as “skip/flag”, not an error to retry. (GET /v1/deals already carries each deal’s status, so you can filter coming_soon out before reaching this call.)

Hide un-claimable deals with claimable_without_eligibility

List and detail responses also include claimable_without_eligibility (boolean). It’s true when a default member: one you create with just an email, can redeem the deal right now with nothing extra supplied, and false when a default member can’t: blocked by a per-member gate (a targeted region, or a non-default eligibility dimension such as eligibility_company_stage or eligibility_funding), or the deal isn’t redeemable yet (coming_soon). Filter or flag on it instead of maintaining your own list of un-claimable deals. It’s partner-relative (region default = your account’s regions) and excludes tier (a premium-only deal is a separate tier_upgrade_required gate). A default member carries no user_types, so user-type-only gates don’t make a deal un-claimable.

Response

{
  "instructions": "<ul><li>Visit the URL</li><li>Enter the promo code</li></ul>",
  "promo_code": "FOUNDER20",
  "redeem_url": "https://vendor.com/redeem",
  "contact_email": "support@vendor.com",
  "deal_status": "live"
}

promo_code, redeem_url, and contact_email are omitted when the deal doesn’t set them. deal_status is always present and is always "live" on a 200: a non-live deal never reaches this shape (coming_soon returns the 409 above; every other status 404s).

See the full filter set and response schema in the Deals API Reference.