Notion

Key Features

• Connects Gravity Forms to Notion using Notion public OAuth.
• Sends form submissions to Notion through the Notion REST API.
• Creates Notion database rows from Gravity Forms entries.
• Maps Gravity Forms fields to Notion database properties.
• Supports Notion property types including title, rich text, number, select, multi-select, checkbox, URL, email, phone, date, status, and more.
• Creates child pages under a selected Notion parent page.
• Creates workspace-level pages when Notion permissions allow.
• Supports markdown body content for page destinations.
• Includes a database picker with live search.
• Caches Notion database schema for faster feed configuration.
• Provides schema refresh via AJAX.
• Includes a parent page picker with paginated search.
• Supports Conditional Logic for feed processing.
• Processes feeds asynchronously to reduce front-end submission impact.
• Handles Notion API rate limits with retry support for HTTP 429 responses.
• Integrates with Gravity Flow using a Notion feed step.
• Supports Gravity Forms logging and feed error handling.
• Includes developer filters for customizing feed processing and Notion payloads.

Requirements

• WordPress 6.8+
• PHP 7.4+
• Gravity Forms 2.9.24+
• A Notion integration using public OAuth
• Access to the Notion workspace, database, or pages you want Gravity Forms to write to

Installation

1. Upload the gravityformsnotion folder to /wp-content/plugins/.
2. Activate the plugin from the WordPress Plugins screen.
3. In WordPress, go to Forms → Settings → Notion.
4. Enter your Notion OAuth Client ID and Client Secret.
5. Register the displayed Redirect URI in your Notion integration settings.
6. Click Connect with Notion to authorize the connection.

Setup: Connecting to Notion

To connect the add-on, you need a Notion public OAuth integration.

Create or configure a Notion integration

1. Go to Notion’s integrations page:https://www.notion.so/my-integrations
2. Create or open your Notion integration.
3. Confirm that the integration is configured for public OAuth.
4. Copy the OAuth Client ID and Client Secret.
5. In WordPress, go to Forms → Settings → Notion.
6. Paste the Client ID and Client Secret.
7. Copy the Redirect URI shown in the Gravity Forms Notion settings screen.
8. Add that Redirect URI to your Notion integration settings.
9. Save the integration settings in Notion.
10. Return to WordPress and click Connect with Notion.
11. Authorize the workspace when prompted.

After authorization, the add-on stores the OAuth connection and uses it when processing Notion feeds.

Using the Add-On: Creating a Feed

Feeds control what happens when a form is submitted.

Go to:

Forms → Choose a form → Settings → Notion

Then:

1. Click Add New to create a new feed.
2. Enter a Feed name.
3. Choose a destination:
   • Database row
   • Child page
   • Workspace page
4. Configure the destination-specific settings.
5. Optionally enable Conditional Logic.
6. Save the feed.

You can create multiple Notion feeds per form if you want different submissions to create different database rows or pages.

Feed Destinations

Database Row

Use this destination to create a new row in a Notion database.

When configuring a database destination:

1. Select or enter the Notion database.
2. Refresh the schema.
3. Select the appropriate data source if required.
4. Map Gravity Forms fields to Notion database properties.
5. Save the feed.

The add-on stores a cached copy of the Notion database schema so the mapping UI can load quickly. Use schema refresh if you add, remove, or rename Notion properties.

Child Page

Use this destination to create a Notion page under a selected parent page.

When configuring a child page destination:

1. Select the parent Notion page.
2. Configure the page title.
3. Optionally configure page body markdown.
4. Use Gravity Forms merge tags to include submitted form data.
5. Save the feed.

Page body content is submitted as markdown. Large payloads may need to be shortened to satisfy Notion limits.

Workspace Page

Use this destination to create a top-level page in the connected Notion workspace.

Workspace page creation depends on the permissions granted to the Notion integration.

When configuring a workspace page destination:

1. Select Workspace page as the destination.
2. Configure the page title.
3. Optionally configure page body markdown.
4. Use merge tags to include form submission data.
5. Save the feed.

Field Mapping

Field mapping is used for Notion database row destinations.

The add-on retrieves the Notion database or data source schema and lets you map Gravity Forms fields to Notion properties.

Supported Notion property types include:

Not all Notion property types are writable in every context. Read-only Notion properties may appear in schema data but cannot always be populated by form submissions.

Page Titles and Markdown Content

For page destinations, configure:

• Page title: Required.
• Page body (markdown): Optional.

Both fields support Gravity Forms merge tags, so submitted values can be included in the generated Notion page.

Example page title:

New Lead: {Name:1}

Example page body:

## Contact Details

Name: {Name:1}

Email: {Email:2}

Message: {Message:3}

Conditional Logic

Conditional logic lets you process a Notion feed only when specific form conditions are met.

Use it to create rules such as:

• Only create a Notion page when a checkbox is selected.
• Only add a database row when a lead source matches a specific value.
• Route different submissions to different Notion destinations.
• Create different feeds for different form choices.

To enable it:

1. Edit the Notion feed.
2. Open the Conditional logic section.
3. Check Enable.
4. Configure the rules.
5. Save the feed.

Gravity Flow Integration

The add-on includes a Gravity Flow feed step for Notion.

Use the Notion step when you want a workflow to control when the Notion feed runs instead of processing immediately on form submission.

If a form has no Notion feeds configured, the workflow step will indicate that a feed should be added under:

Form Settings → Notion

Logging & Troubleshooting

If a submission does not appear in Notion as expected:

1. Confirm the site is connected under Forms → Settings → Notion.
2. Confirm the Notion OAuth Client ID and Client Secret are correct.
3. Confirm the Redirect URI in Notion exactly matches the Redirect URI shown in WordPress.
4. Make sure the connected Notion integration has access to the target workspace, database, or parent page.
5. Confirm the feed is active.
6. Confirm Conditional Logic rules match the submitted entry.
7. For database destinations, refresh the schema after changing Notion database properties.
8. Verify required Notion fields, especially title fields, are mapped correctly.
9. Enable Gravity Forms logging and review the Notion add-on logs.
10. Check feed errors on the Gravity Forms entry if the Notion API returns an error.

The add-on uses asynchronous feed processing to reduce the impact on front-end form submissions. If Notion is temporarily unavailable or rate-limited, errors are logged and feed errors are recorded for troubleshooting.

Notion API

This add-on uses the Notion REST API.

API base URL:

https://api.notion.com/v1

The add-on sends requests with a pinned Notion API version header:

Notion-Version: 2026-03-11

Primary API operations include:

• OAuth token exchange and refresh
• Retrieve the connected integration identity
• Search pages
• Search data sources
• Retrieve databases
• Retrieve data sources
• Retrieve pages
• Create pages

Notion API reference:

https://developers.notion.com

Developer Filters

The add-on includes filters for customizing behavior.

Filter	Description
gform_notion_should_process_feed	Short-circuit feed processing for a specific form/feed.
gform_notion_feed_properties	Modify database properties before the Notion API request.
gform_notion_feed_markdown	Modify markdown body content for page destinations.
gform_notion_feed_children	Provide custom Notion block children for page destinations.
gform_notion_api_rate_limit_retries	Adjust maximum retry attempts after HTTP 429 responses. Hard capped at 10.
gform_notion_oauth_client_id	Override the OAuth Client ID, useful for storing credentials outside the database.
gform_notion_oauth_client_secret	Override the OAuth Client Secret, useful for storing credentials outside the database.

Additional debug-oriented filters may be available for including raw Notion error response bodies in WP_Error data. These should only be enabled temporarily while debugging.

Development

Install PHP development dependencies:

composer install

Run code style checks:

composer phpcs

Auto-fix code style issues:

composer phpcbf

Run static analysis:

composer phpstan

Run unit tests:

composer phpunit

Run Semgrep security scanning:

composer semgrep

JavaScript/package commands are defined in package.json. The current build command is a placeholder until a JavaScript bundle is needed.

Changelog

See change_log.txt for release notes.