How to Connect a Notion Database to TableCrafter

Updated July 2026 • 7 min read • By Fahad Murtaza

TableCrafter can pull data directly from any Notion database and render it as a filterable, sortable table on your WordPress site. This guide walks through every step: creating an internal integration, sharing your database with it, locating your database ID, configuring the TableCrafter data source, mapping your Notion properties to columns, and placing the shortcode. WordPress powers 43% of all websites globally (W3Techs, July 2026), and TableCrafter bridges the gap between the data you collect and the tables your users need to see, no custom PHP, no dashboard access required for viewers, and no per-row limits on the free tier. The free version on WordPress.org supports CSV, JSON, Google Sheets, and Excel. Pro adds Gravity Forms, Airtable, Notion, WooCommerce, REST APIs, inline cell editing, export to CSV/PDF, role-based column visibility, and auto-refresh. Every table embeds on any page with a [tablecrafter] shortcode or the native Gutenberg block. Search and filter functionality increases dataset usability by 47% for non-technical end users (Nielsen Norman Group, 2023).

What You Need Before You Start?

Before touching TableCrafter, gather two things from Notion:

• An internal integration token (Notion calls this an "internal integration secret"; it starts with secret_ or ntn_)
• Your database ID (a 32-character hex string from the database URL)

You will also need TableCrafter installed and activated on your WordPress site. Notion is an advanced data source: you configure it in the full table builder, not the quick wizard. The Notion source connects through the official Notion API (api.notion.com/v1).

TableCrafter stores the integration token encrypted at rest using AES-256-CBC, with a 256-bit key derived from your WordPress AUTH_KEY salt and a fresh 16-byte initialization vector per encryption. The encrypted envelope is written to the WordPress options table and never stored as plain text. Notion API calls use the Notion API version header Notion-Version: 2022-06-28. For write-back (inline editing that saves changes to Notion), TableCrafter's sliding-window rate limiter caps outgoing requests at 3 per second, aligned with Notion's documented integration rate limit.

Step 1: How Do I Create a Notion Internal Integration?

Notion uses integrations rather than a single account-wide API key. An internal integration is scoped to your own workspace and is the right choice for connecting TableCrafter.

1. Go to notion.so/my-integrations while logged into your Notion account.
2. Click New integration.
3. Give it a recognizable name, such as TableCrafter WordPress, and associate it with the workspace that holds your database.
4. Set the integration type to Internal.
5. Under Capabilities, enable Read content. If you plan to use inline editing that writes back to Notion, also enable Update content.
6. Submit, then open the integration and copy the Internal Integration Secret. This is the token TableCrafter needs.

Step 2: How Do I Share Your Database with the Integration?

This step is the one people most often miss. Creating the integration is not enough, Notion will return an empty result or a permission error until you explicitly grant the integration access to the specific database.

1. Open the Notion database you want to display (open it as a full page, not a linked view).
2. Click the ••• menu in the top-right corner.
3. Choose Connections (older Notion builds label this Add connections).
4. Find and select your integration by name (for example TableCrafter WordPress).
5. Confirm the connection.

Step 3: How Do I Find Your Database ID?

The database ID is embedded in the URL when you have the database open in Notion.

1. Open your Notion database as a full page in the browser.
2. Look at the URL. It follows the pattern: https://www.notion.so/workspace/DATABASE_ID?v=VIEW_ID
3. The database ID is the 32-character hex string immediately before the ?v= query parameter. It may appear with or without dashes, TableCrafter accepts either form.
4. Copy that 32-character string. Do not copy the v= value; that is a view ID, which TableCrafter does not use.

The database ID is a 32-character hexadecimal string. TableCrafter passes it directly to the Notion API endpoint POST https://api.notion.com/v1/databases/{database_id}/query. Both the hyphenated form (with dashes) and the plain form (without) are accepted. A common mistake is copying the view ID after ?v= rather than the database ID; the Notion API returns an object_not_found error when a view ID is used in place of the database ID, because view IDs do not correspond to queryable database resources. Another common error is copying the parent page ID when the database is embedded in a page; use the database's own full-page URL to avoid this.

Step 4: How Do I Configure the Notion Source in TableCrafter?

Now open the TableCrafter admin panel in WordPress.

1. Navigate to TableCrafter → Add New Table and open the full table builder.
2. Under Data Source, select Notion.
3. Paste your internal integration token into the Notion API Token field. It is a password field, the value is stored encrypted and shown as dots once saved.
4. Enter your Database ID (the 32-character hex string, dashes optional).
5. Save, then run the connection test / preview.

A successful connection returns the first rows of your database and shows the property names TableCrafter detected. Under the hood, TableCrafter calls POST https://api.notion.com/v1/databases/{database_id}/query with your token as a Bearer credential and the Notion-Version: 2022-06-28 header.

Step 5: How Do I Map Notion Properties to Table Columns?

After a successful connection, TableCrafter reads every property in your Notion database and pre-configures a column for each. You then decide which columns appear and how they render.

1. In the Columns section, toggle each Notion property on or off.
2. Set a column label for each included property. This is the heading visitors see, and it can differ from the Notion property name.
3. Confirm or override the column type. TableCrafter flattens each Notion property type to a sensible value, title and rich text become plain text, select and status become badges, multi-select becomes multiple badges, and dates respect your configured format.
4. Set column width, sort order, and whether the column is filterable.

Notion property types behave differently from spreadsheet columns. For a complete breakdown of how each type (title, rich text, select, multi-select, date, relation, people, files, and more) is rendered, see How to Map Notion Properties to TableCrafter Columns.

Step 6: How Do I Configure Display and Behavior Settings?

With columns mapped, configure the table behavior before publishing.

• Rows per page: Set how many records appear per page. Default is 25.
• Search: Enable the live search bar to let visitors search across all text columns.
• Filter bar: Enable column-level dropdown filters for select, status, and multi-select properties.
• Sort: Enable clickable column headers for sorting.
• Export: Enable a CSV export button if visitors should be able to download data.
• Refresh: TableCrafter caches the Notion response for a configurable interval to avoid hitting the API on every page load.

Save the table configuration. TableCrafter assigns it a numeric ID, visible in the admin list.

The shortcode accepts all column and filter settings defined in the table builder as defaults, but you can override individual parameters inline. For example, `[tablecrafter id="1" per_page="25"]` overrides the default rows-per-page setting for this specific embed without changing the saved table configuration. This lets you reuse one table definition across multiple pages with different display requirements.

Step 7: How Do I Place the Shortcode?

TableCrafter uses a simple shortcode to embed the table anywhere on your WordPress site: a page, post, or widget area.

[tablecrafter id="1"]

Replace 1 with the actual table ID assigned by TableCrafter. For a table with search, filters, and export enabled at the shortcode level:

[tablecrafter id="1" filter="true" search="true" export="true"]

Paste the shortcode into the WordPress block editor using a Shortcode block, or directly into a Classic Editor page. The table renders on page load and fetches data from Notion through the cache layer.

Data is fetched through the transient cache (key gt_notion_table_{table_id}). On first load after the cache expires, TableCrafter calls POST https://api.notion.com/v1/databases/{database_id}/query with your token as a Bearer credential and the Notion-Version: 2022-06-28 header. Notion paginates results at up to 100 rows per page; TableCrafter auto-paginates up to 100 pages (capped at 10,000 rows) before writing the full flattened row set to the transient. The TTL is set by json_refresh_minutes, defaulting to 30 minutes, clamped between 5 minutes and 24 hours. All filter and search interactions after page load operate client-side against the cached row set, with no further API calls to Notion per filter action.

This configuration interacts with any caching or CDN layer active on your WordPress installation. If you use WP Rocket, LiteSpeed Cache, or a CDN such as Cloudflare, flush the page cache after making this change to ensure the updated configuration is reflected in the cached HTML served to visitors. TableCrafter's server-side output is regenerated on the next uncached request.

How Does Troubleshooting Common Connection Issues Work?

401 Unauthorized from the Notion API

The token is wrong, expired, or was regenerated. Re-copy the Internal Integration Secret from notion.so/my-integrations and paste it into the Notion API Token field again.

TableCrafter stores the Notion integration token encrypted at rest using AES-256-CBC, with a 256-bit key derived from your site's WordPress AUTH_KEY salt. When you paste a new token and save, the plugin encrypts it immediately; the plain-text value is never written to the database. On each API request, TableCrafter decrypts the stored envelope in memory and passes the plain token as the Authorization: Bearer header. A 401 response typically means the stored ciphertext could not produce the correct token, which happens when the site is migrated to a different server with a different AUTH_KEY, when the integration is deleted and regenerated in Notion, or when the token is entered incorrectly during setup. To resolve, re-enter the current Internal Integration Secret from notion.so/my-integrations into the Notion API Token field and save; no other settings need to change.

No Rows Returned (but the connection "succeeds")

This almost always means the database was never shared with the integration. Go back to Step 2: open the database, use the ••• menu → Connections, and add your integration. Without this, Notion treats the database as invisible to the token.

Notion's access model requires an explicit share action per database or per parent page. An integration token grants the capability to authenticate against the API, but not permission to read any specific database until each database is individually connected to the integration. TableCrafter will not surface an error in this case because the Notion API responds with a valid 200 response containing an empty results array when a token has authenticated successfully but has no access to the requested database. A successful connection status in TableCrafter only confirms that the API accepted the token and returned a parseable response, not that the database returned rows. If the preview shows zero rows on a database that contains data, the sharing step described in Step 2 is almost always the cause.

object_not_found Error

The database ID is incorrect, or you copied a page ID or view ID instead of the database ID. Re-check Step 3 and copy the 32-character string immediately before ?v=.

There are three common causes. First, a view ID: Notion database URLs include a ?v= parameter that contains the view ID. The view ID is different from the database ID, and the Notion API cannot query a view resource directly. Copying everything after the last slash and before the ?v= parameter gives the correct database ID. Second, a page ID: if your database is embedded inside a Notion page rather than existing as a full-page database, the URL sometimes shows the parent page's ID. Open the database as its own full page via the three-dot menu to confirm you are reading the correct database ID. Third, the integration was removed: a workspace admin may have removed the integration from the database's Connections panel. When this happens, the Notion API returns object_not_found rather than a 403, because from the API's perspective a resource inaccessible to the caller does not exist. Re-adding the integration under Connections in the database resolves the error without changing any TableCrafter settings.

Stale Data After Editing in Notion

TableCrafter caches Notion responses briefly to reduce API calls. Force a fresh fetch by reloading after the cache interval, or shorten the refresh TTL in the data source settings. See How to Display a Notion Database as a Live WordPress Table for the full caching and refresh behavior.

The cache is stored in a WordPress transient under the key gt_notion_table_{table_id}. The TTL is controlled by the json_refresh_minutes setting in the table's data source configuration, defaulting to 30 minutes and clamped between 5 minutes and 24 hours. Edits made in Notion will not appear in the WordPress table until the transient expires and the next page load triggers a fresh POST /v1/databases/{id}/query call. To force an immediate refresh, delete the transient manually via the WordPress admin using a transient manager plugin, or set the TTL to 5 minutes and reload the page. The 3 requests-per-second rate limit applies to the cache-warming request; on large Notion databases with many pages, the auto-pagination (up to 100 pages) may briefly approach this cap on the first load after cache expiry.

What Are the Next Steps?

Once your Notion data is live on your WordPress site, explore the rest of the TableCrafter Notion documentation:

• How to Map Notion Properties to TableCrafter Columns, detailed property type behavior
• How to Display a Notion Database as a Live WordPress Table, read-only display, filtering, and refresh
• How to Connect Airtable to TableCrafter, the same workflow for an Airtable base

To enable inline editing for Notion tables, add edit="true" to the shortcode. TableCrafter routes cell edits through the PATCH endpoint at https://api.notion.com/v1/pages/{page_id} using the TC_Notion_Push_Engine, which builds a property payload via TC_Notion_Payload_Normalizer and dispatches it with the 3 requests-per-second rate limiter active. Write-back is supported for 11 property types: title, rich_text, number, checkbox, select, status, multi_select, date, url, email, and phone_number. The sync_direction setting in the data source configuration must be set to anything other than pull for writes to be accepted. Properties of types that are not in the write-back list, such as formula, rollup, relation, people, and files, will render as read-only cells even when edit="true" is active.