App guides
The Airtable app keeps your Swell orders, customers, products and more in an Airtable base. Every Swell record becomes one Airtable row, which is created, updated and removed as the record changes, so your team can filter, report and plan in Airtable without exports.
Sync can also go the other way. For products, variants, customers, coupons and categories, edits in Airtable to names, SKUs, prices, stock levels and a few other columns are written back to Swell.
| When | What the app does |
| A record of a synced collection is created or updated | Reads the full record and adds or updates its row, matched on the Swell ID column. |
| An order is created or its items change | Updates the order's line-item rows too, and removes the rows of items no longer on the order. |
| A record is deleted | Deletes its row, checks the row's Deleted box, or leaves it alone, as set in the app settings. |
| You run Create tables & columns | Creates the tables and columns the app needs, or adds only the missing columns to tables you already have. |
| You start a backfill | Sends the records a collection already has, one page at a time. |
| Every 5 minutes | Writes edits made in Airtable back to Swell, for the tables you turned on. |
- An Airtable account with a base for your store data. It can be a new, empty base.
- Enough records on your Airtable plan. Airtable limits the records in each base, for example to 1,000 on the Free plan, and line items and variants add up quickly.
Install Airtable from the Swell App Store, and set it up in your test environment before the live one.
Create a personal access token
In Airtable, go to airtable.com/create/tokens and create a token with the scopes data.records:read, data.records:write, schema.bases:read and schema.bases:write. Under Access, add your base. Copy the token, which starts with pat. Airtable shows it only once.
The schema scopes let the app create and check the tables. Without them, create the tables and columns yourself, as listed under Tables and columns.
Copy the base ID
Open the base in Airtable and copy the part of its URL that starts with app. For example, the base ID of https://airtable.com/appXXXXXXXXXXXXXX/tblYYYYYYYYYYYYYY is appXXXXXXXXXXXXXX.
Add them to the app
In Swell, go to Apps > Airtable > Settings and enter the Personal access token and Base ID. Under Collections to sync, check the collections you want; Orders, Customers and Products are checked at first. Change the table names only to use tables you already have. Click Save settings.
Create the tables
Choose Actions > Create tables & columns, then Create. After a few seconds, a message lists the tables and columns created. If it says it isn't finished, run it again. From then on, each change in Swell appears in Airtable within a few seconds.
Test the connection
Choose Actions > Connection test. The app checks the token, the base, the tables and every column and its type, and lists anything that's wrong.
Send your existing records
This step is optional. Open Airtable syncs in the dashboard sidebar and click Backfill all synced collections, then Start. Each backfill shows Completed when it's done.
Place a test order
Place a test order. Within a few seconds, your Orders table has a row for it.
Go live
Settings are saved separately for each environment. Use a separate base for the live environment, so test records stay out of your live tables. Add the live base to your token's access, then in the live environment, repeat steps 2 to 6 with its base ID.
Each record of a collection checked under Collections to sync is one row in its table. When the record is created or updated, the app reads it from Swell and writes the row. Rows are matched on the Swell ID column, so updates never create duplicates. With write-back on for the table, an editable column is written only when that field changed in Swell, so a Swell change can't overwrite an Airtable edit that hasn't been written back yet.
- Each order line item links to its order row, and each variant links to its product row, through the Order and Product columns. Airtable adds the reverse link column to the order or product table.
- When an order is created or its items change, its line-item rows are updated. The rows of items removed from the order are handled like the rows of deleted records.
- When a record is deleted, the When a record is deleted in Swell setting decides what happens to its row: it's deleted, its Deleted box is checked, or it's left unchanged. Deleting an order or product does the same to its line-item or variant rows.
If Airtable rate-limits the app, times out or has a server error, Swell sends the change again later. Other errors, such as a missing table or column, aren't retried, and changes made before the app was set up or while Enabled was off aren't sent. Fix the cause and run a backfill to send them.
A backfill sends the records a collection already has. Backfills are listed under Airtable syncs in the dashboard sidebar, with Active and Failed tabs.
- To backfill one collection, click New airtable backfill, choose the collection and save. To send only newer records, set Created on or after.
- To backfill every synced collection, click Backfill all synced collections. It starts one backfill for each collection checked under Collections to sync that doesn't have an active one.
- Each backfill shows its status, the records done, the total (except for order line items), when it started and finished, and the last error.
- To stop a backfill, open it and choose Cancel. To continue a failed or canceled backfill after its last record, choose Resume.
When a backfill step hits Airtable's rate limit, a timeout or an Airtable server error, the backfill shows Waiting to retry and continues by itself: after 1 minute for rate limits, otherwise after 1, 2, 4 and up to 30 minutes. It fails after 8 retries in a row. Choose Resume to retry right away. Existing rows are updated, not duplicated, so you can run a backfill again at any time.
To write Airtable edits back to Swell, check that Get updates from Airtable is on, which it is at first, and check the tables under Write Airtable edits back to Swell. The table must also be checked under Collections to sync. Every 5 minutes, the app reads the rows edited in those tables and writes the changed cells to Swell. These columns can be edited:
| Table | Columns written back to Swell |
| Products | Name, SKU, Active, Price, On sale, Sale price, Track stock, Stock level |
| Product variants | Name, SKU, Active, Price, On sale, Sale price, Stock level |
| Customers | Email, First name, Last name, Phone, Email opt-in |
| Coupons | Name, Active, Use limit, Valid from, Expires |
| Categories | Name, Slug, Active |
- A Stock level edit sets Swell's stock to that number, recorded as a stock adjustment for the difference. If the product changes in Swell before the edit is written back, for example after a sale, Swell's stock level replaces your edit.
- Price, On sale and Sale price are the standard one-time purchase price. Subscription plan prices aren't synced.
- Name edits change the name in the store's default language. Translations are left alone.
- When a row is checked, every editable cell that differs from Swell is written, including edits made before write-back was turned on. Turn on write-back for a table when its rows match Swell, for example right after a backfill.
- Each run works for about 7 seconds, so a large bulk edit can take several runs to reach Swell.
- Edits to other columns aren't written back, and are overwritten the next time the record changes in Swell. Rows added or deleted in Airtable aren't added to or deleted from Swell.
Airtable pulls in the dashboard sidebar has a row for each check that found edits, with the table, the number of edited records, the records updated in Swell, the edits rejected and the last error. The With rejected edits tab lists the checks with cells that Swell refused or the app couldn't read, for example an emptied name, a duplicate SKU or text in a number column. A rejected cell keeps its Airtable value until that field changes in Swell or a backfill runs.
Create tables & columns creates these tables, with typed columns. The first column is the table's primary field. Dates are in UTC, and each table also has a Swell ID column and a Deleted checkbox.
| Table | Columns |
| Orders | Number, Date created, Status, Paid, Delivered, Refunded, Canceled, Customer email, Customer name, Items, Item count, Subtotal, Shipping, Tax, Discount, Total, Refunded amount, Currency, Shipping method, Shipping address, Coupon, Date updated |
| Order line items | Item, Order (link), Order number, Order Swell ID, Item Swell ID, Product, Variant, SKU, Product Swell ID, Variant Swell ID, Quantity, Price, Discount, Tax, Total, Currency, Order date |
| Customers | Email, First name, Last name, Phone, Type, Group, Email opt-in, Order count, Order value, Currency, Date created, Date updated |
| Products | Name, SKU, Slug, Type, Active, Price, On sale, Sale price, Track stock, Stock level, Stock status, Date created, Date updated |
| Product variants | Name, Product (link), Product Swell ID, SKU, Active, Price, On sale, Sale price, Stock level, Currency, Date created, Date updated |
| Subscriptions | Number, Status, Active, Paid, Canceled, Customer email, Customer name, Product, Product Swell ID, Plan, Interval, Quantity, Price, Recurring total, Currency, Period start, Period end, Date canceled, Date created, Date updated |
| Coupons | Name, Code, Multiple codes, Description, Active, Discounts, Uses, Use limit, Valid from, Expires, Currency, Date created, Date updated |
| Categories | Name, Slug, Active, Parent, Parent Swell ID, Description, Date created, Date updated |
In Order line items, Swell ID holds the order ID and the item ID joined by a hyphen, because Swell reuses item IDs across orders. The item's own ID is in Item Swell ID.
You can add your own columns, and the app leaves them alone. You can also change a column to a compatible type, such as Status to a single select or Total to a currency column. If you made the tables yourself, Create tables & columns adds only the missing columns. Run it again when you check another collection, or when an app update adds a column.
If a column has a type the app can't write into, Create tables & columns and Connection test report it. To fix it, run Create tables & columns with Replace columns with the wrong type turned on. Each wrong column is renamed to <name> (old), keeping its data, and created again with the right type. Then run a backfill to fill it.
| Where | What it's for |
| Apps > Airtable > Settings | The token and base, the synced collections, write-back, the table names, deletions, the backfill page size and the Enabled switch. |
| Apps > Airtable > Actions | Create tables & columns and Connection test. |
| Airtable syncs in the sidebar | The list of backfills, with New airtable backfill and Backfill all synced collections. |
| A backfill | Its status and progress, the last error, and Cancel or Resume. |
| Airtable pulls in the sidebar | A row for each check that found Airtable edits, with the edits updated in Swell and rejected. |
Settings are in Apps > Airtable > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Personal access token | From airtable.com/create/tokens, with access to your base. Masked on the settings page. Required. | None |
| Base ID | Starts with app. The part after airtable.com/ in the base's URL. Required. | None |
| Collections to sync | The collections synced live and covered by Backfill all synced collections. Order line items needs Orders, and Product variants needs Products. | Orders, Customers, Products |
| Get updates from Airtable | Every 5 minutes, writes Airtable edits to Swell for the tables checked below. Turn it off to stop reading Airtable; Swell changes still go to Airtable. | On |
| Write Airtable edits back to Swell | The tables whose editable columns are written back to Swell. The table must also be synced. | None |
| Orders table, Order line items table and the other table names | The name or ID (starting with tbl) of each table. Names must match exactly, including case. | The collection's name, such as Orders |
| When a record is deleted in Swell | Delete the Airtable row, keep the row and check its Deleted box, or keep the row unchanged. | Delete the Airtable row |
| Backfill page size | Records, or order line items, sent per backfill step, from 1 to 100. Lower it if backfills often wait for rate limits. | 50 |
| Enabled | Turns off all syncing without uninstalling the app. Running backfills fail with a message. | On |
- Only the columns listed under Editing in Airtable can be written back. Orders, line items and subscriptions are read-only in Airtable.
- Airtable edits usually reach Swell within 5 minutes, and large bulk edits take several runs. If the same field changes in Swell in the meantime, the Swell value wins and overwrites the Airtable edit. A backfill also overwrites edits that haven't been written back yet.
- Descriptions, coupon discounts, addresses and other columns that hold a summary of the Swell value can't be written back.
- Stock locations aren't supported, and stock level edits with fractions are rejected.
- Column names and what they hold are fixed. You can add columns, but you can't rename synced ones.
- Airtable can't change a column's type through its API, so a replaced column keeps its data in <name> (old), and the new column stays empty until a backfill or the next change. Delete the old column yourself.
- Line-item backfills don't remove the rows of items that were removed from orders earlier. Live sync does. Orders with hundreds of items can take longer to send than a function is allowed to run.
- Only single-code coupons show their code. The codes of multi-code coupons aren't synced.
- Airtable allows 5 requests per second per base, so large backfills take a while, and running many at once on a busy store slows everything down.
- Values longer than 100,000 characters are cut off.
A failed backfill shows the error on the backfill, and a check with rejected edits shows it under Airtable pulls. The app also logs each change it can't send. In the Swell dashboard, the logs are under Developer > Console > Logs.
Enter the Personal access token and Base ID in the app settings and click Save settings. The message also appears when Base ID isn't just the part that starts with app, for example when it's the base's full URL.
The message says what's wrong. Check that the token has access to the base and the data.records:read and data.records:write scopes, and that the base ID starts with app. Without schema.bases:read, the test only checks that the tables can be read.
Check that the collection is checked under Collections to sync and that Enabled is on. Changes fail with a missing table or column error until the tables exist, so run Create tables & columns. If you renamed a table in Airtable, update its name in the settings, or use the table's ID, which never changes.
Run Create tables & columns with Replace columns with the wrong type turned on, then run a backfill for that collection.
Waiting to retry means Airtable rate-limited the app or had an error, and the backfill continues by itself. If backfills often wait, lower Backfill page size. If a backfill failed because the base is full, free up records or upgrade your Airtable plan. Then open the backfill and choose Resume.
If two rows have the same Swell ID, for example after you copied a row, updates to that record fail, and so does any backfill that reaches it. Delete one of the rows, then resume the backfill.
Check that Get updates from Airtable is on, that the table is checked under Write Airtable edits back to Swell and Collections to sync, and that the column can be edited. Wait up to 5 minutes. If the check shows Edits rejected, Last error under Airtable pulls says why. Errors in a check that hasn't found an edit yet, such as a missing column, are only in the logs.
After an app's permissions change, Swell can deny some requests for a while. Backfills wait and retry, and Swell sends live changes again. If it keeps happening, reinstall the app.
Uninstalling the app stops syncing to Airtable and writing Airtable edits back, and removes Airtable syncs and Airtable pulls from your dashboard sidebar. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Your Airtable base and its rows stay as they are. If you no longer need the personal access token, delete it at airtable.com/create/tokens.
| Function | Runs on | What it does |
| record-events | Created, updated and deleted events of orders, accounts, products, product variants, subscriptions, coupons and categories | Reads the full record and adds, updates, deletes or flags its row and its line-item or variant rows. |
| pull-edits | Every 5 minutes | Reads the rows edited in each write-back table and writes the changed cells to Swell. |
| create-tables | The Create tables & columns action | Creates missing tables and columns, and replaces wrong-type columns when asked. Stops after 8 seconds and asks to be run again. |
| connection-test | The Connection test action | Checks the token, the base, the tables, the columns and their types. |
| sync-run | sync.created and sync.updated, while the backfill is pending or running | Sends one page of records, sorted by ID after the last record sent, and saves the progress. Saving it starts the next step. |
| sync-retry | The backfill's retry time, while it's waiting | Sets the backfill back to pending, so sync-run retries the step. |
| sync-all | The Backfill all synced collections action | Starts a backfill for each synced collection that doesn't have an active one. |
| sync-control | The Cancel and Resume actions | Sets the backfill to canceled, or back to pending. |
Backfills are stored in the app collection apps/airtable/syncs, with collection, status, date_from, last_id, pages, sent, total, last_error, retries, date_retry, date_started and date_completed. Write-back checks are stored in apps/airtable/pulls, with table, status, found, changed, failed, date_cursor, date_pass_started, offset, date_completed, last_error and date_last_error. Checks that find no edits aren't saved.
The app calls the Airtable Web API. Rows are upserted with performUpsert on the Swell ID column, 10 records per request, with typecast: true, and the app waits about 220 ms between requests. Tables and columns are created with the Meta API. Write-back polls Airtable with LAST_MODIFIED_TIME() on the editable columns rather than using Airtable webhooks.
Swell builds and maintains the Airtable app. For help with the app, email support@swell.is. For questions about your Airtable account, plan or base, contact Airtable.