Trolleywell for BigCommerce: setup and user guide
What Trolleywell does
Trolleywell shows the requester's BigCommerce orders in the Zendesk ticket sidebar (and on user profiles): items with current stock, totals, shipping, payment, shipments and tracking, refunds, order messages and staff notes, with their lifetime value and average order. Agents you allow can refund an order in full or in part, change its status and add a staff note. Every action asks for confirmation first and is logged on the ticket as an internal note.
1. Create a store-level API account in BigCommerce
In the BigCommerce control panel: Settings > Store-level API accounts > Create API account. Choose token type V2/V3 API token and name it "Trolleywell for Zendesk".
| OAuth scope | Setting | Why |
|---|---|---|
| Orders | modify to allow refunds, status changes and staff notes; read-only for a view-only sidebar | Orders, items, shipping, shipments, messages, refunds |
| Customers | read-only | Finding the customer account behind an email |
| Products | read-only | Current stock and availability of the items on an order |
| Channel listings | read-only | Naming the storefront or marketplace an order came from |
Every other scope can stay at None. Click Save. BigCommerce shows the Access token and the
API path (like https://api.bigcommerce.com/stores/abc123/v3/) once, and downloads them as a
text file. Keep that file safe until the token is in Zendesk, then delete it.
What each scope allows in Trolleywell:
| Trolleywell feature | Scope | BigCommerce endpoint |
|---|---|---|
| Orders, lifetime value, lookup | Orders read-only | GET /v2/orders, GET /v2/orders/{id} |
| Items, shipping, tracking, messages | Orders read-only | GET /v2/orders/{id}/products, /shipping_addresses, /shipments, /messages |
| Refunds on the order | Orders read-only | GET /v3/orders/{id}/payment_actions/refunds |
| Customer account | Customers read-only | GET /v3/customers |
| Current stock | Products read-only | GET /v3/catalog/products |
| Channel names | Channel listings read-only | GET /v3/channels |
| Refund quote and refund | Orders modify | POST /v3/orders/{id}/payment_actions/refund_quotes, POST .../refunds |
| Change status, add a staff note | Orders modify | PUT /v2/orders/{id} (status or staff notes only) |
If a scope is missing, the sidebar names it. Edit the same API account in BigCommerce to add it; the token stays the same.
2. Install and connect
- In the Zendesk Marketplace, open Trolleywell and choose Install, then the Standard plan. The 14-day trial starts and Zendesk asks for a card. Billing starts when the trial ends unless you uninstall.
- Store hash or API path: paste the API path from step 1. Trolleywell reads the store hash
from it (the part after
/stores/). The bare hash or your control panel address (store-abc123.mybigcommerce.com) work too. - Access token: paste the token. Zendesk stores it as a secure setting. It is never sent to agents' browsers, and Zendesk only adds it to requests going to api.bigcommerce.com.
- Store name (optional): shown in the sidebar and in ticket notes.
3. Multi-storefront and several stores
- Channels per brand: if your store sells on several storefronts or marketplaces (BigCommerce
multi-storefront), map each Zendesk brand to its channel ids, like
360001: 1; 360002: 1002. Channel ids are in Channel Manager in BigCommerce; Zendesk brand ids are in Admin Center > Account > Brand management. Agents see that brand's orders first and can click Show all channels. - Stores 2 and 3: fill in the store hash and token of another BigCommerce store to turn it on. Brands for this store lists the Zendesk brand ids whose tickets open it first. Agents can switch stores in the sidebar.
4. Who may take actions
- Who may take actions:
admin(the default),agentfor everyone, custom role ids, orgroup:<id>, separated by commas. Everyone else sees orders read-only. - Each action can be switched off: Allow refunds, Allow status changes, Allow staff notes.
- Largest refund without an admin: in the order's currency; 0 means no limit. Admins have no limit.
- Actions work on tickets only (each one is logged there). New tickets and user profiles are read-only.
5. Matching orders to the requester
Trolleywell searches by every email address on the requester's Zendesk profile (up to five), finds BigCommerce customer accounts with those emails, and reads orders by billing email (guest checkouts) and by customer account. An order shows only when its billing email is one of the requester's addresses or it belongs to one of their accounts. Archived orders are left out.
If customers use different emails in your store, set User field with the BigCommerce customer id to the key of a Zendesk user field that holds their customer id. Email matching still runs.
No match? Type an order number or an email in the lookup box.
The sidebar reads the 50 newest orders per email and per account. When there are more, lifetime value says "last N orders".
6. Refunds
- Open the order and click Refund.
- Pick what to refund: a quantity per item, shipping per shipping address, or a custom amount (a goodwill or price adjustment at order level, refunded without tax). Give a reason; it is saved on the refund in BigCommerce with the ticket number.
- Click Get refund quote. BigCommerce works out the amount and tax and lists the ways the money can go back. Nothing changes yet.
- Pick a way: Back to the original payment (through the payment provider), or Record as refunded offline when you return the money another way. If BigCommerce only offers offline (bank deposit, cash on delivery, check, or a provider that allows one online refund per order), the reason it gives is shown.
- Read the confirmation and click Refund. If you change the pick after the quote, get a new quote first.
What to know:
- The provider processes the refund after BigCommerce accepts it. If it declines, the sidebar and the ticket note say "declined" and no money moved.
- Some providers only refund settled payments; BigCommerce says so when you ask for the quote.
- BigCommerce does not put refunded items back in stock through its API. Adjust stock in the control panel when items come back.
- BigCommerce sets the order to Partially Refunded or Refunded, and may email the customer depending on your order status notification settings.
7. Status changes and staff notes
- Change status: Awaiting Fulfillment, Awaiting Shipment, Awaiting Pickup and Completed are offered for paid orders only, so an unpaid order is never shown as paid. Manual Verification Required holds an order; Cancelled stops it and does not refund anything. Shipped statuses come from shipments, refunded statuses from refunds and payment statuses from the provider, so they are not offered. Refunded and cancelled orders are not changed from the sidebar.
- Add staff note: Trolleywell reads the order's staff notes right before writing and adds a new line with the date, the agent and the ticket number below them. It never writes over notes your team added in the control panel.
8. Logged on the ticket
After BigCommerce accepts an action, Trolleywell adds an internal note to the ticket (order,
amounts, reason, payments, agent, their note) and a tag: trolleywell_refund, trolleywell_status
or trolleywell_staff_note. Use the tags in views, triggers and reports.
If BigCommerce's answer is lost on the way (a timeout), Trolleywell re-reads the order before saying anything: if the action happened, it logs it; if not, it says nothing changed. It never sends an action twice on its own.
9. Troubleshooting
| The sidebar says | What to do |
|---|---|
| "is not a store hash" | Paste the API path from the API account (or the part after /stores/) |
| "did not accept the access token" | The API account was deleted or the token belongs to another store. Create a new API account and paste its API path and token together |
| "does not have the scope this needs (...)" | Edit the API account in BigCommerce and set the named scope |
| "has no store with the hash" | The store hash is mistyped |
| "rate limiting" | Wait a few seconds and click Refresh. Other apps share the store's API quota |
| "No orders in ... for ..." | The billing email differs. Use the lookup box, add the address to the Zendesk user, or map a user field |
| Refund is greyed out | The red box says why: no quote yet or the pick changed, over what is left, over the refund limit, no reason |
| No actions at all | Your role or group is not in "Who may take actions", the action is switched off, or this is a new ticket or a user profile |
10. Uninstalling
Uninstall in Admin Center > Apps and integrations > Zendesk Support apps. That deletes the settings and the stored tokens. Also delete the API account in BigCommerce. Internal notes and tags on tickets stay. Nothing was created in your Zendesk account or BigCommerce store by the installation itself.
Questions: hello@greatwork.company. We reply within one business day.