BigCommerce

UNTESTED on a real store. The adapter (app/lib/outcomes/sources/bigcommerce.ts) and its order fetch are tested against fixtures and a fake API built from the public BigCommerce v2 / v3 shapes; the fetch has never run against BigCommerce, and the checkout script has never run on a storefront.

How it works

BigCommerce webhooks carry no signature and no order: they say which order changed (store/order/statusUpdated, store/order/created, ...). OrcLink checks a secret header you set on the webhook, then reads the order and its refunds from your store with an API token. So the order in OrcLink is the store's own record, never the webhook's.

1. Make an API account

BigCommerce admin > Settings > API > Store-level API accounts > Create API account. Token scopes: Orders: read-only and Order Transactions: read-only. Keep the store hash (the abc123 in https://api.bigcommerce.com/stores/abc123/v3/) and the access token.

2. Connect in OrcLink

Pick a long webhook secret (openssl rand -hex 32). Dashboard > Integrations > BigCommerce: paste store_hash:api_token:webhook_secret (for example abc123:xxxxxxxxxxxx:0123...) and Connect. Copy the webhook URL. The three values are stored encrypted in one value (the connect form takes one field). A value in another form is refused at connect (400, with the form to use).

The connection is bound to the store hash you paste (one store per connection); a webhook from another store hash is ignored with a note.

3. Create the webhook through the API

curl -X POST https://api.bigcommerce.com/stores/STORE_HASH/v3/hooks \
  -H "X-Auth-Token: ACCESS_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"scope":"store/order/*","destination":"<OrcLink webhook URL>","is_active":true,
       "headers":{"X-Orclink-Secret":"<the webhook secret>"}}'

store/order/* covers created, updated, status updated and refund created. OrcLink reads only those four; every other order scope (messages, transactions, archived) is ignored without a fetch. A webhook whose producer is another store hash is ignored with a note.

4. The tag and the click id

Storefront > Script Manager > Create a script (two scripts):

1. Name OrcLink tag, location Header, pages All pages, category Analytics, type Script: <script async src="https://t.YOURDOMAIN.com/t.js?w=WORKSPACE_ID" data-w="WORKSPACE_ID"></script> (as a "Script contents" snippet, without the outer tag if the form asks for JS only).
2. Experimental. Name OrcLink order click id, location Footer, pages Checkout, category Functional, type Script: the contents of orclink-checkout.js.

Step 2 is experimental and has never run on a real storefront. It keeps one line orclink_olid=ol_... in the shopper's order comment (customer_message) through the Storefront Checkout API. Each time the checkout page loads it writes or replaces the line from a valid orc_olid cookie, and removes an older line when there is no valid cookie (no consent, consent withdrawn, expired). Limits, plainly:

• The click id is written into the shopper-visible order comment, so the shopper and the merchant can see it, and BigCommerce prints the comment on invoices and packing slips. The Storefront API offers no hidden field for it (order metafields are server-side only).
• A shopper can type the line by hand. OrcLink bounds that: an olid matches an order only when its click happened before the order, and an olid on orders of many different customers stops matching (see the help page).
• The checkout page keeps its own copy of the comment and can rewrite it (when the shopper types in the box or continues), which loses the line.
• Without the line, the order is still recorded, but unattributed (or matched by the buyer's hashed email when an earlier order carried the olid).

A more reliable path would write an order metafield from a small server-side piece after the created webhook; that is not built, and OrcLink does not read metafields yet.

What OrcLink does with an order