Setup guide: Deal Approvals & Stage Gate
This guide covers installing Deal Approvals & Stage Gate in HubSpot, the permissions it asks for, setting up approval policies and the Approvals card, using HubSpot’s pipeline rules on Professional, and disconnecting or uninstalling the app, including what happens to your data.
1. Before you start
- You need to be a super admin in HubSpot, or have the App Marketplace access permission, to install the app.
- The app works on every HubSpot plan, including the free CRM and Starter. HubSpot’s pipeline rules (section 6) need Sales Hub Professional or Enterprise; workflows (section 8) need a Professional or Enterprise subscription.
- Approvers need a HubSpot user in the account. A view-only seat is enough to approve from the card.
2. Install the app
- Install Deal Approvals & Stage Gate. Once the app is listed on the HubSpot App Marketplace, you can also install it from its listing.
- Choose the HubSpot account to install into.
- HubSpot shows the permissions screen (section 3). Leave the optional permissions on if you want the app to set HubSpot’s pipeline rules for you or use the workflow action. Click Connect app.
- While the app is not yet listed on the HubSpot App Marketplace, HubSpot shows a notice that the app has not been reviewed by HubSpot. This is normal for new apps.
- After connecting, HubSpot opens the app’s home page. You can open it again any time from the Marketplace icon in the top navigation, under your apps.
Right after install, the app creates a deal property Approval status in its own property group Deal approvals. The user who installed the app becomes the first app admin.
3. Permissions the app asks for
| Permission | Scopes | Why the app needs it |
|---|---|---|
| Deals | crm.objects.deals.read, crm.objects.deals.write | Read the stage, pipeline, amount and the properties your conditions use, and the stage history; move a deal back or on; write the Approval status; add notes and tasks to the deal |
| Deal property settings | crm.schemas.deals.read, crm.schemas.deals.write | List deal properties for the conditions editor; create the Approval status property |
| Owners | crm.objects.owners.read | List users and teams to choose approvers and to find the deal owner’s team |
| Workflows (optional) | automation | Complete the “Request deal approval” workflow step when the decision is made |
| Pipeline rules (optional) | crm.pipelines.governance.read, crm.pipelines.governance.write | Read and set “restrict skipping stages” for your approval stages |
| Stage editing permissions (optional) | crm.pipelines.stage_permissions.read, crm.pipelines.stage_permissions.write | Limit editing of deals in the waiting stage to your approvers |
HubSpot leaves the optional permissions out when your subscription does not include the feature. The app then explains how to set the rules by hand. Full details are in the permissions and data table.
4. Create an approval policy
Open the app settings: Marketplace icon > Connected apps > Deal Approvals & Stage Gate > Settings, and click Add a policy.
- Pipeline: one policy per pipeline. The Free plan covers one pipeline.
- First stage that needs approval: this stage and every later stage are gated, except closed lost. A deal can always be closed as lost.
- Waiting stage (optional): a stage before the gate where deals wait. Moving a deal there opens a request by itself, and approval moves the deal on to the first gated stage.
- Which deals need approval: add conditions, for example Amount is at least 10000, Discount is greater than 15, Deal type is any of New business, or Deal owner’s team is any of Nordics. With no condition, every deal in the pipeline needs approval.
- Who approves: one or more steps. Each step has approvers (users, teams, or the deal owner’s team lead on Pro) and needs any one or all of them. On Pro, add up to 5 steps in a row, each with its own conditions, for example a Finance step only from 100000.
- Click Save policy. It applies from the next stage change.
Also in the settings:
- How requests and decisions work: automatic requests when a deal is moved back, moving the deal on approval, tasks for approvers and for the deal owner, and whether deal owners may approve their own deals. The person who requested can never approve.
- Team leads (Pro): name the lead of each team, for steps that go to the deal owner’s team lead.
- Changes that always pass: other apps by HubSpot app ID, users, imports and workflows. The settings list the sources the app moved back recently, with a button to let one pass.
- App admins: who can change the settings. Everyone else sees them read only.
- Refresh users and pipelines: after you add users, teams or stages in HubSpot.
5. Add the Approvals card to deal records
The card is not added to record pages automatically. Once per account:
- Marketplace icon > Connected apps > Deal Approvals & Stage Gate > Settings > App cards.
- Next to Approvals, click Manage locations, tick Default view under Record page (right sidebar), and click Save.
You can also add it in Settings > Objects > Deals > Record customization > your view > Add cards > Card library. After a reinstall, add the card again: HubSpot removes it from record views when the app is uninstalled.
6. HubSpot pipeline rules (Sales Hub Professional and up)
HubSpot’s pipeline rules stop most unapproved moves before they are saved; the app catches the rest. In the app settings, under Tip for Sales Hub Professional, click Set rules for your pipeline. The app then:
- turns on Restrict deals from skipping stages for the waiting stage and the first gated stage, so reps cannot jump past them;
- with a waiting stage, sets Control deal editing access for that stage to your approvers, so reps cannot edit or move a deal while it waits.
To set the rules by hand: Settings > Objects > Deals > Pipelines > choose the pipeline > Pipeline rules. Super admins, users with permission to edit property settings, workflows and other apps can bypass HubSpot’s rules; the app still moves their unapproved changes back.
7. Use the app
Request approval
- Move the deal into the waiting stage, or into a gated stage. The app moves it back if needed, writes a note and opens the request. Or click Request approval on the Approvals card, choose the stage and add a comment.
- Approvers get a HubSpot task Approve deal: [deal name]. The card shows who the request is waiting for.
Approve or reject
Open the deal. On the Approvals card, add a comment and click Approve, or add a reason and click Reject. With several steps, the next step’s approvers get their task when a step is complete. When the last step is approved, the app moves the deal to the requested stage (you can turn this off). A rejection sends the deal owner a task with the reason; a deal in the waiting stage goes back to where it came from.
After approval
The approval covers the requested stage and every later stage. If the amount goes up, or another value that decides the policy changes, the next move into a gated stage needs a new approval. The card says what changed.
Approvals page and history
The app’s home page lists the requests waiting for you and all pending requests. History shows every move back, request and decision. Pro exports it as CSV.
Automations
The deal is in the gated stage for about one to two seconds before the app moves it back. A workflow or a sequence that starts on “deal entered stage” can run in that moment. Trigger such automations on Approval status is Approved, or on a stage after the gate, instead.
8. Workflow action (Pro, HubSpot Professional and Enterprise)
In a deal-based workflow, add the action Request deal approval (under Deal Approvals & Stage Gate). It opens a request under the pipeline’s policy and waits up to 7 days for the decision. Branch on its output Approval status: approved, rejected, cancelled or not required. The step is part of the app’s Pro plan.
9. Plans and billing
The Free plan needs no payment. To upgrade, open the app’s home page > Plans and choose Pro; payment runs through Stripe. Manage billing opens Stripe’s billing portal for invoices, the card and cancelling. See plans and pricing.
10. Disconnect the app
In the app settings, under Disconnect and delete data, type DELETE and click Disconnect and delete data. The app uninstalls itself from the account, revokes its access and deletes what it stored for that account at once: policies, requests and the approval history. A paid plan is cancelled at the end of the paid period.
11. Uninstall the app
In HubSpot, click the Marketplace icon > Connected apps, find Deal Approvals & Stage Gate, and choose Uninstall. The app’s access ends immediately. HubSpot’s own steps are in its knowledge base article Uninstall an app.
12. What happens to your data
- Your deals stay as they are. Notes and tasks the app created stay on the deals. The Approval status property and its values stay in HubSpot; delete the property in property settings if you no longer want it.
- What the app stores while installed: your HubSpot account ID and name, the installing user’s ID and email address, encrypted access tokens, your policies and settings, approval requests (deal ID and name, requested stage, approvers’ names, user IDs and email addresses, comments, the values the approval was given for), the approval history, and short-lived copies of your pipelines and the list of users and teams (refreshed every few minutes).
- After uninstall: tokens are deleted at once. Policies, requests, history and the cached lists are deleted as soon as the app learns of the uninstall (within the hour, or at once when you use Disconnect). The remaining account record and any plan record are deleted 30 days after uninstall.
- Retention while installed: the history is kept for 30 days on Free and 12 months on Pro. Approved requests are kept while the app is installed, because they let approved deals move on.
- The app never reads contacts, companies, tickets or other records, and stores no deal data beyond the fields above.
- Details: privacy policy, security, data processing agreement.
Permissions and data
| Data | Access | Why |
|---|---|---|
| Deals (stage, pipeline, name, amount, owner, the properties your conditions use, stage history) | Read and write | Check stage changes against the policy, move deals back or on, write the Approval status |
| Notes and tasks on deals | Write | Explain moves and decisions on the deal; give approvers and owners a task |
| Deal property settings | Read and write | Conditions editor; create the Approval status property |
| Deal pipelines and stages | Read | Policy editor and gate decisions |
| Owners and teams | Read | Approvers, team leads, owner-team conditions |
| Pipeline rules and stage editing permissions (optional) | Read and write | Set HubSpot’s own rules for your approval stages |
| Workflow action callbacks (optional) | Write | Finish the “Request deal approval” workflow step |
| Account details (account ID, name, account type, time zone) | Read | Show the account name and apply plans to the right account |
Help
Email support@kayabyte.dev with your HubSpot account ID. We answer within one business day. See also support.