BuyerClearDocumentation
Everything a merchant needs to run BuyerClear: what it checks, what one approval changes in Shopify, and what happens after.
Updated 7 September 2026. This guide describes the latest pilot version, currently in a separate test installation. Existing installations may show an earlier version. Public installation and paid billing are pending; live-store acceptance is still required.
- What it does
- Install and permissions
- Set up before the first buyer
- Plans and approved buyers
- Invite buyers
- Evidence you compare
- What a registry answer means
- Deciding
- What approval changes in Shopify
- Expiry, renewal and re-checks
- What the buyer can do alone
- Buyers list and exports
- Limits
- When something goes wrong
What it does
A buyer enters their professional licence type, issuing authority, state, exact number, holder and expiry. The shop can make a supporting file optional. BuyerClear compares these details with a registry configured for that class and authority, and adds a reading of any uploaded document. A person reviews the evidence and decides. Shopify access becomes active only after the approved changes are read back successfully.
Nothing approves automatically. A register can confirm an exact identifier and report its status, expiry and sometimes a holder name. The name is compared locally and never selects a registry row. A registry result does not prove the scan is genuine or decide who enters your shop.
Install and permissions
BuyerClear is in pre-release testing and is not listed in the Shopify App Store. Contact us to discuss a pilot and compatibility review. A development-store installation is not a public launch.
It asks for these scopes and uses each of them:
| Scope | Why |
|---|---|
read_companies, write_companies | Create the company and location for an approved buyer, and read the grant back before access counts. |
read_customers, write_customers | Attach the customer as company contact, read verification-request tags, and optionally synchronize approval tags and a decision receipt. |
read_markets, write_markets | List your B2B markets in settings and seat an approved location in the one you picked. |
read_products, write_products | Read the catalogs attached to a market so settings can show what a buyer would gain. The configured write scopes include their corresponding read permissions; staff actions also require the user’s own permissions. |
Of Shopify’s protected customer data, BuyerClear requests one field: the customer email, used to find an existing customer when a buyer is already in your store. It does not request name, phone or address.
Set up before the first buyer
The app opens on a checklist. Configure the access destination and confirm the shop’s credential policy before the first approval.
- Catalog access. In Shopify, create a B2B market whose members are specific company locations and attach your trade catalogs. Select it in Settings → Catalog access. To hide trade-only products from retail visitors, exclude them from all Region catalogs in Shopify. Test a signed-out visitor and a signed-in buyer before inviting customers. The selected market locks after the first grant.
- Buyer requirements. In Settings → Buyer requirements, choose professional licence, resale certificate, either, or both. Professional form profiles can make the file optional and ask for the licence type and issuing authority. Resale certificates need the original file. Requirements lock after the first submission.
- Reseller tax. Off by default. Switch it on and a resale certificate approval assigns the Texas reseller exemption on the buyer’s location. A professional license never turns tax off.
- File storage and reminders. Buyer requirements shows the document-retention period, normally 90 days from submission; each application shows its deletion date. New shops use a reminder 30 days before expiry. These timings are not editable in Settings. Resale originals must be downloaded for your own tax archive.
- Application form. In Settings → Application form, add up to five text, long-text or choice questions. Save and preview the form before inviting anyone. Buyer pages are currently in English.
- Branding. In Settings → Branding, upload a PNG or JPEG to display beside your shop name on the application, status and update pages. BuyerClear hosts the uploaded image; it does not import your theme logo. BuyerClear remains in the footer as the application provider.
- Email alerts. Set your notification and reply-to addresses in Settings → Email alerts. An optional approval tag is configured in Catalog access and removed when BuyerClear suspends its grant.
- Payment terms. Optionally select a Shopify payment-terms template for approved company locations. Existing different terms are not overwritten; approval does not create an invoice or charge.
- Share the decision. Before the first grant, optionally enable a customer decision receipt and reserved status tags. Other installed apps can read the receipt; raw registry records and documents are never included. This setting locks after the first grant.
Plans and approved buyers
Free includes 5 distinct approved buyers and one deciding reviewer. Core is planned at $29/month for additional approved buyers with one deciding reviewer. A place is used on a buyer’s first approval, not on submission; declines and renewals do not use another place. The allowance does not reset monthly. Paid billing requires a separate confirmation in Shopify.
Billing shows the counter, subscription-check time and a link to Shopify’s pricing page when configured. Shopify asks you to approve a paid plan. Reaching the free limit never creates a charge. A downgrade does not remove existing access or block privacy requests. Free/Core reviewers can explicitly transfer the deciding seat in Billing without changing past decisions.
Invite buyers
New shops start with an invite-only portal. From Applications → Invite a buyer, create a single-use link with an expiry, then send it to the buyer. The portal carries your shop name. There is no open-portal switch in the current Settings screen.
The buyer types their business, contact name and email, credential kind, issuing state, number exactly as printed including leading zeroes, holder name and expiry. Professional profiles also ask for the licence type and issuing authority. A PDF, JPEG or PNG up to 10 MB is optional when the shop chooses a professional form profile; resale certificates always need a file.
Staff can also open Verification requests from Applications to see customers tagged buyerclear_verify. The page reads the first 50 requests and links to existing applications when known. The tag does not send an invitation, supply evidence or approve a buyer automatically.
Evidence you compare
Every application compares entered details with the registry. When a file was submitted, its extracted fields appear as a third source; a form-only application clearly says no document was provided.
- What the buyer typed
- Never overwritten by anything the app reads. A discrepancy is information, not an error to be corrected away.
- What the document shows
- A vision model reads images; PDFs are read from their text layer. Scanned PDFs without readable text need a photo or manual reading of the original. If extraction fails, the application still reaches you with that limitation clearly marked. Extraction can misread or invent fields and never decides a buyer’s eligibility.
- What the register says
- An exact source-specific match on the number, never a fuzzy one. The review records when BuyerClear queried the source. Publisher refresh times are separate facts in the source catalog and must not be mistaken for the query time.
Differences between the three are listed as flags on the review page, each with a severity, so a mistyped digit and an expired license do not look alike.
What a registry answer means
The application sends only the credential kind, jurisdiction, number and, for scoped professional checks, licence type and issuing authority to the separate BuyerClear Registry Worker. The Worker queries only enabled sources configured for that authority and licence class. Legacy unscoped applications keep their original lookup behavior. It receives no buyer name, email, document, shop identifier or application identifier. Current source status and policy are published on the coverage page.
| Answer | What it means | What to do |
|---|---|---|
| Found | The register holds this number. It also tells you the status and expiry it holds, which may differ from the document. | Compare the name and status, then decide. |
| Several matches | The number belongs to more than one record. Some authorities number licences per board, so one number can identify multiple records. | Open the official source and compare all evidence. The app will not choose by name. |
| Not found | A register that is up to date does not hold this number. | Treat it as a serious flag. Check the number for a typo before declining. |
| Look it up on the official site | No register we read covers this state and credential, so the app links to the state’s own search and says what that search covers. | Check by hand, then decide. |
| Cannot answer | The source was unreachable, or it stopped being refreshed and so cannot prove a credential is missing. | Retry or check the official source manually. Temporary failures marked retryable are retried daily while the application awaits review. |
The distinction between the last two and “not found” is the point of the design. A source that said nothing must never look like a source that said no.
Deciding
Three outcomes: approve, decline, or ask for changes. A buyer-visible explanation is required for a decline or request for changes; the buyer sees that note.
Decisions require a current staff session in Shopify Admin and an explicit protected action. Notifications do not grant review authority; legacy bearer review links are retired. Opening any link never approves an application.
Every decision quotes the revision it was made against. If two people decide the same application at the same time, one of them succeeds and the other is told the application moved on. Nothing is decided twice.
What approval changes in Shopify
Approval runs a sequence that can be resumed if any step fails, and access is not marked active until Shopify confirms it.
| Step | What happens | How it is confirmed |
|---|---|---|
| Company | A new company and location are created for the buyer. If the customer already belongs to a company, staff must select and confirm the existing location before approval. | Company, contact and location are checked against Shopify. |
| Payment terms | Your optional selected template is applied only if terms are unset or already match. | Template ID read back from the company location. |
| Tag | Your approval tag is applied to the customer, if you set one. | Recorded on the step. |
| Expiry | For a location BuyerClear creates, the credential expiry is stored on the company location. Existing linked location expiry data is preserved; BuyerClear tracks the credential separately. | Written before access is granted. |
| Tax | For an approved Texas resale certificate, and only if enabled, the Texas reseller exemption is assigned to the location. | Exemption read back on the location. |
| Market | The location joins the B2B market you chose. | Membership read back. |
| Access | Only now is the grant marked active and the buyer told. | If read-back fails, the grant stays failed and no approval mail goes out. |
| Decision receipt | If enabled, synchronize buyerclear.verification and one reserved status tag after confirmed access. | Version-aware write and read-back; synchronization failures remain visible and retryable. |
The optional receipt includes the human decision’s identifiers, dates, evidence hash, declared credential kind, jurisdiction and expiry, plus the registry query time. It excludes names, email, license numbers, private links, documents and raw source records. The reserved tags are buyerclear_verified, buyerclear_not_verified and buyerclear_expired. Suspension removes buyer-linked receipt details. Unrelated tags and the incoming request tag stay unchanged. Tags and receipts are display data, not checkout authorization or tax advice. Storefront API access is off; Liquid theme compatibility still needs a live-store check.
Expiry, renewal and re-checks
A daily job watches every approved credential.
- Expiry reminders use the shop’s configured policy; new shops default to 30 days before expiry. This schedule is not editable in Settings.
- After expiry, BuyerClear removes the market membership and exemption it owns, unless another approved credential still qualifies the buyer. Access or tax treatment granted outside BuyerClear is preserved. Shopify must confirm the removal.
- A renewal approved before the old date passes defeats the pending suspension, so a buyer who renews in time is never cut off by a job queued earlier.
- On an existing Volume plan, an approved credential is rechecked every 90 days where an enabled source supports it. If the register no longer confirms it, a staff-review alert appears. Access is not touched automatically. Expiry checks and privacy operations run on every plan.
- The uploaded document is scheduled for deletion under the shop’s stored retention policy, normally 90 days from submission. The decision, the reading and the register answer stay in the record.
What the buyer can do alone
Each application has a status page at its own reference. The buyer sees the state of the application, the reason if you asked for changes, and a masked form of the address you will reply to.
If you asked for changes, the buyer can send an update without needing a new invitation. Opening the prefilled form asks for the email address on the application first. This is a matching check, not an email-ownership verification. The buyer should keep the status link private.
Buyers list and exports
The approved-buyers page shows credentials and Shopify grant state. An existing Volume plan adds application and buyer CSV exports. Individual evidence downloads and mandatory privacy exports remain available on every plan. Exports never carry document bytes or storage keys.
Resale originals are scheduled for deletion 90 days after submission by default. The application shows the deletion date. Download the original and individual evidence export before deletion; your shop keeps its own tax archive for the required retention period. These downloads are available on every plan. BuyerClear is not a tax-certificate archive.
Limits
- One B2B market per shop, chosen in settings and locked after the first grant.
- Shopify Basic, Grow and Advanced allow up to three active catalogs across B2B markets. Plus supports unlimited catalogs and direct assignment to company locations. See Shopify’s catalog guide.
- Uploads: PDF, JPEG or PNG, 10 MB, one document per application. The type is checked by file signature, not by what the browser claims.
- Professional pilot scope and source policy are listed in the Registry coverage and source-policy table.
- The public pages are rate limited per address: five submissions and thirty status views a minute.
- No automatic approval.
When something goes wrong
An approval says access failed
Shopify refused or did not confirm a step. Approval and access are separate states. A failed or uncertain Shopify step can leave partial remote changes; BuyerClear attempts to remove its own changes and requires read-back before confirming the outcome. Open the application to see which step and retry. Check the reported error, selected market and catalogs, and the deciding staff member’s Shopify permissions.
The registry keeps saying it cannot answer
A temporary failure marked retryable is retried daily while the application awaits review. A stale or unsupported source needs a manual check. Use the official link and record the evidence for your decision.
The document could not be read
The application still reaches the queue with the original file attached and the reading marked as failed. Staff can retry the reading, which never changes what the buyer typed. For a scanned PDF without readable text, ask for a clear JPEG or PNG, or read the original manually.
A buyer says they never got the email
Check the application’s history: every message is recorded with its outcome. Failed send attempts can be retried; acceptance by the mail provider does not prove inbox delivery. The buyer can also use the private status link shown after submission.
A job is stuck
Background work is visible to staff, with the failed ones listed and requeueable. Payloads are not shown, because they carry buyer data.