Perks Tools
Offers, partner collaboration and analytics.
Read offers, partners and privacy-filtered analytics. Saving or duplicating a draft changes saved data immediately but does not publish or email partners. Publication, live updates, deletion and partner actions return a preview with effects and email recipients. Ask for explicit approval before confirm_workspace_action; changed state or recipients require a fresh preview.
Use list_workspaces to choose a workspace. The schemas returned by tools/list describe the deployed version.
list_perks
List own, shared or open partner perks, twenty per page. Pure read; does not provision a company.
Permission: perks:read. workspaceId is required.
| Parameter | Notes |
|---|---|
filters | Required. scope?: mine|shared|open, includeEnded?: boolean, page?: nonnegative integer, category?: PerkCategory |
get_perk
Read a perk visible to this workspace. Redemption secrets remain hidden for unaccepted partner perks.
Permission: perks:read. workspaceId is required.
| Parameter | Notes |
|---|---|
filters | Required. perkId: string, open?: boolean (for an open partner offer) |
search_perk_partners
Search active B1 workspaces eligible for perk invitations.
Permission: perks:read. workspaceId is required.
| Parameter | Notes |
|---|---|
filters | Required. search?: string |
get_perk_partners
Read active and ended collaborators of a perk this workspace owns.
Permission: perks:read. workspaceId is required.
| Parameter | Notes |
|---|---|
filters | Required. perkId: string |
get_perk_analytics
Read the app analytics with its workspace timezone and privacy suppression. Maximum 366 days.
Permission: perks:read. workspaceId is required.
| Parameter | Notes |
|---|---|
filters | Required. scope?: mine|shared, from?: ISO date or UTC timestamp, to?: ISO date or UTC timestamp, bucket?: day|week|month, perkId?: string, partnerId?: string |
save_perk_draft
Create or edit a draft without publication or emails. Refuses live perks. Omitted fields and partners are preserved on edits. Supply perkId only to edit an existing draft. Use prepare_perk_publish afterwards.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
draft | Required. Optional perkId, plus request: {perk: {title, description, imageUrl, category, price, discountAmount, discountCode, perkType, discountType, availableFrom, expiresAt, redeemLink, ctaLabel, requiresEmail, requiresJoin, marketingOptInText, openToPartners, publishInCreatorSpace}, collaboratorCompanyExternalIds?: string[], message?: string}. Timestamps are epoch milliseconds. IDs must come from search_perk_partners. |
duplicate_perk
Copy a perk owned by this workspace into a new draft with draft partner invitations. Sends no emails and does not publish.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
perkId | Required. Owned perkId |
prepare_perk_publish
Publish a saved draft with its current fields and invitations. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string, request?: {perk: fields to change using save_perk_draft schema, collaboratorCompanyExternalIds?: string[], message?: string} |
prepare_perk_update
Change a live perk; omitted fields and partners are preserved. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string, request?: {perk: fields to change using save_perk_draft schema, collaboratorCompanyExternalIds?: string[], message?: string} |
prepare_perk_delete
Disable a perk and remove it from every collaborating Space. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string |
prepare_add_partner_perk
Host an eligible open partner perk for this Space members. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string |
prepare_perk_invitation_response
Accept or decline a pending perk invitation. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string, operation: accept|decline |
prepare_leave_perk
Stop hosting a partner perk in this Space. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string |
prepare_manage_perk_partner
Resend or cancel an invitation, or remove a collaborating partner. Preview only, with email recipients and effects; makes no business change or email. Show the preview and obtain explicit approval, then call confirm_workspace_action. If state or recipients change, prepare again.
Permission: perks:write. workspaceId is required.
| Parameter | Notes |
|---|---|
input | Required. perkId: string, partnerId: company external ID, operation: resend|cancel|remove, message?: string |