CartPass

Documentation

Set up CartPass on your Webflow store, and see exactly what it adds to your site.

What CartPass does

CartPass adds customer accounts to Webflow Ecommerce stores. Shoppers can create an account, sign in, and see their orders, delivery progress, invoices, saved addresses and profile. Store owners get a dashboard of orders and customers, can add customers, and can create roles (for example "Wholesale") to show content only to some customers. They also get sign-in and security controls, transactional emails and campaigns, and developer tools. The app and this documentation are in English; the shopper-facing widget can be translated.

Install

  1. Install CartPass in Webflow and choose the store(s) to connect. Webflow asks you to approve access; if you choose Deny, nothing is connected.
  2. You land on the CartPass dashboard. Your past orders are copied from Webflow in the background.
  3. Publish your site in Webflow. The account widget goes live when your site is published. CartPass publishes it only if you click Publish changes in Settings and confirm; otherwise you publish in Webflow yourself.

What CartPass adds to your site

CartPass adds one script to your site through Webflow's Custom Code API. You don't paste any code.

WhatA hosted JavaScript file, https://cartpass.app/widget.js, registered as "CartPass" with a fixed version and a subresource integrity hash, so the file your visitors load is exactly the reviewed build.
WhereSite-wide, in the footer of every page. It runs on your published site only, not in the Designer.
What it doesAdds a "Sign in" link (or "My account" once a shopper is signed in) to your navbar (or a slim bar at the top when the site has no navbar), the sign-in popup, and the account pages. It shows or hides elements you mark with the attributes below. It doesn't change, restyle or remove your own content, and it never reads your checkout or payment fields.
What it sendsOnly what shoppers type into the CartPass forms (name, email, password, phone, addresses), sent over HTTPS to https://cartpass.app. A sign-in token is kept in the browser's local storage so shoppers stay signed in. No tracking or advertising.
WhyWebflow Ecommerce has no customer accounts; the script is how shoppers reach theirs.

CartPass also registers two Webflow webhooks (new order, order changed) so order history stays current.

Permissions CartPass asks for

sites:readRead your site's name and domains, so only your domains can use your store's accounts.
sites:writeCreate the two order webhooks, and publish your site only when you click Publish changes in Settings and confirm.
ecommerce:readRead orders, to show shoppers their order history and you your dashboard.
ecommerce:writeSave tracking numbers you add in the dashboard to the order in Webflow.
custom_code:writeAdd the script above, update it, and remove it when you disconnect.
authorized_user:readYour name and email, to create your dashboard account.

Set up your store

Install checker

In Settings → Store → Install & domains, Check install status asks Webflow for your store's published addresses, opens each one and looks for the CartPass script. The Stores page has the same check. Each address gets one result:

ResultMeaningWhat to do
FoundThe script is on the page.Nothing.
DuplicateThe page loads CartPass more than once, for example an old copy pasted by hand.Remove the extra copy in Webflow under Site settings → Custom code, then publish.
MissingThe script isn't on the page.Use Reinstall script, then publish your site.
UnreachableThe address didn't open (unpublished or behind a password).Publish the site, or remove the password.

The check reads the published HTML only. A script added later by a tag manager isn't seen.

Sign-in

Shoppers sign up and sign in from a popup that the widget adds to your pages. Under Authentication → Methods you choose which ways are available:

MethodHow it works
Email and passwordAlways on. Shoppers confirm their email with a link. Password rules are in Security settings.
Passwordless linkThe shopper asks for a one-time link by email and signs in by opening it. Turn it on or off; you can also make it the first option in the popup, with the password one click away. When it is off, the option disappears and the server refuses link requests. Its email template can't be switched off while this method is on.
Google, Facebook, GitHub, LinkedInA "Continue with" button for each method you switch on. See Social sign-in.

A method you switch off is simply not shown, and the server refuses requests made for it. Signing in with a method never creates a second account for the same email address in your store.

Until a shopper has confirmed their email, their order list stays empty and they are asked to confirm first. This protects order details from someone who signs up with another person's address.

Social sign-in

Each provider is configured per store under Authentication → Methods. For Facebook, GitHub and LinkedIn you create an app with that provider and paste its client ID and client secret into CartPass; the secret is stored encrypted and never shown again. Google can use either CartPass's shared Google app (shoppers then see CartPass on the consent screen) or your own credentials (shoppers see your app name).

When you create the app, the provider asks for a redirect (callback) URL. Use exactly this form, with the provider name in the middle:

https://cartpass.app/oauth/google/callback
https://cartpass.app/oauth/facebook/callback
https://cartpass.app/oauth/github/callback
https://cartpass.app/oauth/linkedin/callback

A mismatch here is the most common reason a button does nothing. The same address is shown, with a copy button, next to each provider in the dashboard.

Redirects

Under Authentication → Methods → Redirects choose where shoppers land:

AfterChoices
Sign-upThe account page (default), the page they were on, or a custom address.
Sign-inThe account page (default), the page they were on, or a custom address.
Sign-outYour home page, the page they were on (default), or a custom address.

A custom address must be a path on your store that starts with /, or an https address on one of your allowed domains. Anything else is refused when you save, and the default is used instead.

Sign-up form

Under Authentication → Methods → Signup form options you can turn on or off: asking for a name, asking for a phone number, and the "News and offers" checkbox. A Preview signup form button shows a read-only picture of the result. Extra profile questions are covered in Custom fields.

Address book

In the account area, Addresses lets a signed-in shopper keep up to 20 saved addresses.

Order tracking

The Orders page in the account area lists the shopper's orders from Webflow, with search, a date range and an export to CSV. Orders placed as a guest are matched to the account when the email address is the same. Open an order to see its items, addresses, totals, status and tracking.

Delivery stages

Webflow knows an order as pending, unfulfilled, fulfilled, refunded or disputed. CartPass adds the stages Webflow doesn't have, and you set them yourself on the dashboard Orders page (or through the API for the data it exposes). A Webflow re-sync never overwrites a stage you set. The shopper sees one combined status:

Pending · Processing · Shipped · Out for delivery · Delivered · Cancelled · Returned · Refunded · Disputed

Each stage you set, and each new order, also fires the matching webhook event and, if switched on, the matching order email.

Tracking links and invoices

Roles

A role is a label you give to some customers, such as "VIP" or "Wholesale". Create roles under Roles in the dashboard: each has a name, an optional description and a short value (the slug, for example wholesale) that is shown when you create it.

<div data-af-role="wholesale,vip">Trade prices</div>

Roles in the widget only tidy the layout. Anything truly private must come from the server after sign-in, not sit in a hidden element on the page.

Show content to signed-in customers

Add these custom attributes to any element in the Designer (Element settings → Custom attributes). The Playground lets you copy them and try them out.

AttributeEffect
data-af-show="logged-in"Shown only to signed-in shoppers.
data-af-show="logged-out"Shown only to signed-out visitors.
data-af-show="verified"Shown only to shoppers who confirmed their email.
data-af-role="wholesale"Shown only to customers with that role (comma-separate several roles). Create roles under Roles.
data-af-can="view:prices"Shown only to customers whose role includes that permission (comma-separate several; any one is enough). Create permissions under Developer → Permissions.
data-af-field="name", "email", "phone" or a custom field keyFilled with that detail of the signed-in shopper; empty when signed out.
data-af-order="latest-status", "latest-total" or "count"Filled with the status or total of the shopper's latest order, or how many orders they have. Empty when signed out or when there are no orders.
data-af-action="logout" or "open-account"Makes any element sign the shopper out (after a confirmation) or open their account.
data-af="account"Draws the account pages inside this element instead of in a full-screen layer.
data-af-navPlaces the account links in this element. The links the widget writes there use data-af-go (login, signup, orders, logout); for your own buttons use data-af-action.

The widget also adds a few elements of its own that you can style or target from your CSS: data-af-popup (sign-in popup), data-af-page (full-screen account page) and data-af-topbar (top bar for sites with no navbar). To try the rules without signing in, load the script with data-af-preview="guest", "customer" or "customer:wholesale"; it makes no network calls and uses a made-up customer (add data-af-preview-permissions="a,b" to give that customer permissions).

<span data-af-field="name"></span>
<div data-af-show="logged-out">Sign in to see your orders</div>
<a href="#" data-af-action="open-account">My account</a>

These attributes only tidy the layout. Anything truly private must not be in the page; customer data is only ever loaded from CartPass after sign-in.

Custom fields

Under Settings → Store → Custom fields you can add extra details to every customer profile, such as Company or VAT number. You can have up to 20 fields.

Segments

A segment is a saved filter on your customers, shared across your stores. Open Segments in the dashboard to see each one with a live count, view the matching customers, export them as CSV, edit or delete. Every condition you fill in must match:

Six templates start you off: New this week, Unverified emails, No role yet, Quiet for 30 days, Never ordered and Big spenders. A segment can be chosen as the audience of a campaign.

Authentication and security

The Authentication section has three pages: Methods (covered in Sign-in), Security and Connected apps.

Security settings

SettingWhat it does
Bot protectionShoppers may be asked to pass a short security check before an account is created or a sign-in or link is requested. It only runs when your CartPass install has the check configured; the Security page tells you if it doesn't. If the check service can't be reached, shoppers are let through and rate limits still apply.
Block disposable email addressesRejects new sign-ups from known throwaway inboxes. On by default.
Always allow / always block domainsA blocked domain is always refused. An allowed domain is accepted even if the disposable check would refuse it.
One session per shopperSigning in on a new device signs the shopper out of the others.
Session length1 to 90 days. The default is 30.
Password rulesMinimum length 8 to 32 characters; optionally require a number and a symbol; block very common passwords, checked against a built-in list on the server.
Sign-in protectionAfter 3 to 20 failed sign-ins for one email (default 5) the account is locked for 1 to 1,440 minutes (default 15). An address that fails far more often than that is locked too.
Sign out all shoppersEnds every shopper session at once. Only the workspace owner can do this.
Two-step verification for shoppersOff by default. When you turn it on, each shopper can switch it on in Personal & Security (they confirm with their password), and you can switch it on or off for any customer on their page in Customers. A shopper who has it on is asked, after a correct password, for a 6-digit code sent to their email. The code works once, for 10 minutes; five wrong codes end the attempt and count toward the sign-in lockout. A new code can be sent every 30 seconds. It applies to password sign-in in the account popup and in Connected apps; email-link and social sign-in already prove the inbox or the provider account and don't ask for it. Email history never shows a code.

Connected apps

Connected apps turn your store's customer accounts into a sign-in service. CartPass acts as an OpenID Connect provider, so another site or app you build can let your customers sign in with their CartPass account. Only the workspace owner manages them, under Authentication → Connected apps.

  1. Create an app: give it a name (shoppers see this on the approval screen), choose its type and add its redirect URLs. Each URL must match exactly. Use https, or an app scheme such as myapp://oauth. You can add up to 10 URLs per app and have up to 25 apps per store.
  2. Copy the client ID. A web app with a server also gets a client secret, shown once; keep it on the server. A browser app or a mobile or desktop app is a public client: it has no secret and must use PKCE.
  3. Point your OpenID library at the discovery document, which lists everything else.
EndpointAddress
Discoveryhttps://cartpass.app/oidc/<siteId>/.well-known/openid-configuration
Authorizehttps://cartpass.app/oidc/<siteId>/authorize
Tokenhttps://cartpass.app/oidc/<siteId>/token
User infohttps://cartpass.app/oidc/<siteId>/userinfo
Signing keyshttps://cartpass.app/oidc/<siteId>/jwks.json

<siteId> is your Store ID, and the issuer is https://cartpass.app/oidc/<siteId>.

Emails

The Emails section covers two kinds of mail: the transactional emails CartPass sends to shoppers because of something they did, and campaigns you write and send yourself. Mail goes out through CartPass's mail service. Delivery reports such as bounces and complaints depend on your mail provider being connected; until then the history shows the email as sent but not delivered or bounced.

Transactional emails

Open Emails → Transactional to edit the subject, heading, message and button text of each email, with a live preview and a "send me a test" button. Twelve emails are available:

EmailSent whenDefault
Email verificationA new shopper must confirm their address.On, locked
Password resetA shopper asks to reset a password.On, locked
Passwordless sign-in linkA shopper asks for a link.On; locked while that method is on
Sign-in codeA shopper with two-step verification signs in with their password.On; locked while two-step verification for shoppers is on
Account invitationYou add a customer from the Customers page.On, locked
Account deletedAn account is removed.On
WelcomeA shopper confirms their email for the first time.Off
Order placedAn order is placed.Off
Order shippedAn order is marked shipped; includes tracking.Off
Out for deliveryYou set that stage.Off
Order deliveredYou set that stage.Off
Order cancelledYou set that stage.Off
Return receivedYou set an order's stage to Returned.Off

Locked emails can't be turned off, because shoppers would be locked out of their accounts. The order emails are off until you switch them on.

Insert variables in the subject and body by typing them in double braces, or pick them from the chips in the editor. Only the variables an email allows are accepted, and values are escaped, so a shopper's name can never become markup. Emails that carry a secure link must keep {{action_url}}.

VariableValue
{{customer_name}}The customer's first name, or "there".
{{customer_email}}The customer's email address.
{{store_name}}Your store name.
{{account_url}}A link to the account page.
{{support_email}}Your support email.
{{action_url}}The secure link in verification, reset, sign-in and invitation emails.
{{order_number}}, {{order_total}}For order emails.
{{tracking_number}}, {{tracking_url}}For shipped and out-for-delivery emails.

The older short forms {{store}}, {{name}} and {{email}} still work.

Sender verification

Campaigns are sent from an address on your own domain. Add it under Emails → Campaigns, then publish three DNS records at your domain host:

RecordHostPurpose
TXTyour domainSPF: says CartPass's mail service may send for you.
CNAMEcartpass._domainkey. + your domainDKIM: lets receivers check the message was not altered.
TXT_dmarc. + your domainDMARC: tells receivers what to do with mail that fails the checks.

The dashboard shows the exact value for each record and checks them for you. A sender is verified only when the records are found. Free mailbox addresses (for example at a public webmail provider) can't be used as a sender, because nobody can prove they own those domains; they are fine as a reply-to address. Changes at your DNS host can take a while to appear.

Email history

Emails → Transactional → Email history lists the emails CartPass sent, newest first. Filter by status, email type, address or date. Open a row to see the email exactly as it was sent. Failed or bounced emails can be sent again by team members who may do so. Statuses beyond "sent" (delivered, bounced, complained) appear only when your mail provider reports them back to CartPass.

Campaigns

A campaign is one email to a group of customers. Emails → Campaigns → New campaign is a three-step wizard.

  1. Write. Name, subject (up to 150 characters), preview text, one of five layouts and the message. {{customer_name}} and {{store_name}} are filled in for each person. Send yourself a test first.
  2. Audience. Everyone, or a saved segment, in one or more stores. The page shows how many people will receive it.
  3. Review. Choose the sender, then send now or schedule. A schedule must be at least 5 minutes ahead and at most 90 days. You can edit or cancel a scheduled campaign until it starts.

Developer

The Developer section of the dashboard has your store ID and API keys, webhooks, the attribute Playground and permissions.

Store ID and script

Developer → Keys & IDs shows your Store ID and the widget script for it. CartPass normally adds the script for you; use this snippet only if you add it by hand in Site settings → Custom code.

<script src="https://cartpass.app/widget.js"
  data-af-site="YOUR_STORE_ID"
  data-af-api="https://cartpass.app"></script>

Use one copy only; a second copy is ignored and shows up as a duplicate in the install checker.

API keys

Create keys under Developer → Keys & IDs. A key looks like cp_live_… and is shown once, when you create or reset it; CartPass stores only a hash. A read key can only fetch data; a full key can also change customers. Resetting or deleting a key stops it working at once. Keep keys on your server, never in a Webflow page or in the widget script. Each key's last use is shown so you can spot an unused one.

Public API

Send the key as a bearer token to https://cartpass.app/v1/api. Every response covers only the store the key belongs to.

curl "https://cartpass.app/v1/api/customers?limit=20" \
  -H "Authorization: Bearer cp_live_your_key"

curl -X PATCH "https://cartpass.app/v1/api/customers/CUSTOMER_ID" \
  -H "Authorization: Bearer cp_live_your_full_access_key" \
  -H "Content-Type: application/json" \
  -d '{"role":"wholesale"}'
EndpointWhat it does
GET /customersList customers, newest first. Query: limit (1 to 100, default 25), cursor, email. The reply has customers and nextCursor; pass it as cursor for the next page, and it is null on the last.
GET /customers/:idOne customer, with role, permissions and custom fields.
PATCH /customers/:idChange role (a role slug, or null to remove it), name, phone or fields. Full keys only. A role change sends a role.changed webhook.
GET /ordersList orders, newest first. Query: limit, cursor, customerId. The reply has orders and nextCursor.
GET /orders/:idOne order, by its Webflow order ID, with items, addresses, totals, status, delivery stage and tracking.
GET /rolesThe store's roles, each with its permissions.
StatusMeaning
400The request is not valid (an unknown role, a bad phone number or field value, or a bad query).
401The key is missing, wrong or revoked.
403A read key tried to change data, or the store is disconnected.
404No such customer or order in this store.
429More than 600 requests a minute on one key. Wait and retry.

Webhooks

Add an endpoint under Developer → Webhooks (up to 5 per store), choose the events it receives and keep the signing secret it shows you. CartPass sends an HTTPS POST with a JSON body for each event. The address must be public: addresses that point to private networks are refused.

Events

EventSent when
customer.signupA shopper creates an account.
customer.verifiedA shopper confirms their email.
customer.loginA shopper signs in.
customer.deletedA customer account is deleted.
role.changedA customer's role is assigned, changed or removed.
order.placedA new order is synced from your store.
order.processing, order.shipped, order.out_for_delivery, order.delivered, order.cancelled, order.returnedAn order reaches that stage.
test.pingYou press Send test on an endpoint.

Every request has this shape. data carries details for the event, such as orderId, trackingNumber or roleName. siteId repeats storeId under its older name.

{
  "id": "evt_0b6f2a1e-3c1d-4e8f-9a7b-5d2c1e0f4a63",
  "type": "order.shipped",
  "createdAt": "2026-11-03T10:15:30.000Z",
  "storeId": "30b96f48-3069-4caa-a18d-5fc8b5b6a691",
  "siteId": "30b96f48-3069-4caa-a18d-5fc8b5b6a691",
  "customer": { "id": "5d0c3c55-2b1e-4f43-9a52-1f3a8f0b7e11", "email": "asha@example.com" },
  "data": {
    "customer": { "id": "5d0c3c55-2b1e-4f43-9a52-1f3a8f0b7e11", "email": "asha@example.com" },
    "orderId": "65f1a2b3c4d5e6f7a8b9c0d1",
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://track.example.com/1Z999AA10123456784",
    "carrier": "UPS"
  }
}
HeaderValue
X-CartPass-EventThe event type.
X-CartPass-IdThe event id (evt_…). The same event retried keeps the same id, so use it to ignore duplicates.
X-CartPass-TimestampUnix time in seconds when the request was signed.
X-CartPass-Signaturet=<timestamp>,v1=<hex>. During a secret rotation the header carries two v1 values; accept either.

Delivery and retries. Respond with any 2xx status within 10 seconds. Anything else counts as a failure and is tried again, up to three attempts in all, with a growing wait (about 30 seconds, then about a minute). The delivery logs show each attempt with its status code, delay and a snippet of your reply, and a failed delivery can be retried from there by hand. You can switch on an email alert for failed deliveries under Notifications.

Rotating a secret. Use Rotate secret on an endpoint to make a new one. For the next 24 hours CartPass signs each request with both the new and the old secret, so you can deploy the new one without dropping events. After that only the new secret is used.

Verify a webhook

The signature is an HMAC-SHA256, keyed with your endpoint's signing secret, of the timestamp, a dot, and the raw request body, written in hex. Check it before trusting the request, and reject old timestamps.

import crypto from "node:crypto";

// Use the raw body (a string or Buffer), not re-serialised JSON.
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = Number(parts.find(([k]) => k === "t")?.[1]);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;

  const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return parts.some(([k, v]) => {
    if (k !== "v1" || !v || !/^[0-9a-f]{64}$/i.test(v)) return false;
    return crypto.timingSafeEqual(want, Buffer.from(v, "hex"));
  });
}

Playground

Developer → Playground lists every attribute from the table above with its accepted values and an example you can copy. It also lets you try the show and hide rules for a made-up guest or customer, without signing in, using the preview mode of the script.

Permissions

Roles say who a customer is; permissions say what they may do. Create permissions under Developer → Permissions (up to 100 per store). A name uses lowercase letters, digits, :, _ and -, up to 64 characters, such as view:wholesale-prices. Give each role the permissions it should have; a customer gets the permissions of their role, and a customer without a role has none.

<a href="/pricing" data-af-can="view:wholesale-prices">Wholesale prices</a>

Team and access

Under Settings → Team & access the owner can invite people to the workspace. An invite is sent by email and expires after 7 days. You can limit a member to some of your stores. There are four roles:

AreaOwnerAdminSupportViewer
Workspace and teamFullNoneNoneNone
Plan and billingFullRestrictedNoneNone
Store settings, emails, developer toolsFullFullNone (can see webhook logs and email history)Read-only
Customers and orders (edit customers, add tracking, assign roles)FullFullFullRead-only
Campaigns and segmentsFullFullNoneRead-only
Danger zone (delete customers, disconnect stores), connected apps, sign out all shoppersFullNoneNoneNone

The limits are enforced by the server, not only hidden in the menus. A workspace always keeps at least one owner.

Notifications

Settings → Notifications chooses which emails CartPass sends to you, and for which of your stores. New-customer emails, new-order emails and product updates are off until you turn them on; the others are on by default. The options are:

Quiet hours hold alerts during a time window you set, in a time zone you pick, and send them as a digest afterwards.

Translations

Settings → Store → Translations lets you add languages and translate what shoppers see: the widget, its messages and the emails. English is built in, and anything you leave empty falls back to English. One language is the default; you can also match the shopper's browser language. You can edit one string at a time, or import and export a CSV or JSON file. Right-to-left languages are supported. The dashboard itself stays in English.

Settings → Store → Legal & business holds the links shoppers see in the widget (terms, privacy, refunds and returns, shipping, and support or help) and your business details: name, contact details and postal address. The postal address is used in the footer of every campaign, so campaigns can't be sent without it. A preview shows how the links look in the widget.

The dashboard

Disconnect or uninstall

  1. In the dashboard, open Stores and click Disconnect. CartPass removes its script and webhooks from the site and deletes its access token.
  2. Publish your site so the script is gone from the live pages.
  3. Uninstall CartPass in Webflow under Site settings → Apps & Integrations.

If you uninstall in Webflow first, CartPass loses access and can no longer remove its script. The script then switches itself off (it shows nothing), and you can remove it in Site settings → Custom code, then publish. Or reinstall, disconnect, and uninstall again. Either way, your store's data is deleted within 30 days; see Data deletion.

Pricing

Every plan has all the features. Plans differ only in how many customers and stores they cover. There are no transaction fees: CartPass never touches your shoppers' payments.

PlanPriceCustomersStores
Free$0251
Starter$9 / month1001
Growth$29 / month5003
Pro$49 / monthUnlimited5

Launch offer: 50% off every paid plan for as long as you stay subscribed, applied when you subscribe.

Upgrade, downgrade or cancel any time in the dashboard under Plan & billing. Upgrades are charged pro rata. When you cancel, your plan stays active until the end of the period you paid for. If you reach your customer limit, new sign-ups on your store pause until you upgrade; existing customers and their orders are never removed. Fees are billed in USD by Webnotics Pvt Ltd, not by Webflow, and payments are processed by Stripe.

Need help?

See Support or email support@webnotics.solutions.