Basketwell for WooCommerce: setup and user guide
What Basketwell does
Basketwell shows the requester's WooCommerce orders in the Zendesk ticket sidebar (and on user profiles): items, totals, shipping, payment, refunds, tracking and order notes, with their lifetime value and average order. Agents you allow can refund an order in full or in part, change its status, resend an order email and add an order note. Every action asks for confirmation first and is logged on the ticket as an internal note.
1. Create a REST API key in WooCommerce
In WordPress: WooCommerce > Settings > Advanced > REST API > Add key.
| Field | Value |
|---|---|
| Description | Basketwell for Zendesk |
| User | A shop manager or administrator. A dedicated user (for example "zendesk-support") makes the store's order notes and logs clearer. |
| Permissions | Read for a view-only sidebar. Read/Write to allow refunds, status changes, order emails and order notes. |
Click Generate API key. WooCommerce shows the consumer key (ck_...) and the consumer secret
(cs_...); the secret is shown only once, so copy both now.
What each permission allows in Basketwell:
| Basketwell feature | Key permission | WooCommerce endpoint |
|---|---|---|
| Orders, customer, lifetime value, tracking, order notes, lookup | Read | GET /customers, GET /orders, GET /orders/{id}/notes |
| Which emails can be resent for an order | Read | GET /orders/{id}/actions/email_templates (WooCommerce 9.8+) |
| Refund | Read/Write | POST /orders/{id}/refunds |
| Change status | Read/Write | PUT /orders/{id} (status only) |
| Resend an order email | Read/Write | POST /orders/{id}/actions/send_email (WooCommerce 9.8+) |
| Add an order note | Read/Write | POST /orders/{id}/notes |
2. Store requirements
- HTTPS with a valid certificate (WooCommerce only accepts key and secret over HTTPS, and Zendesk's proxy requires a complete certificate chain).
- Permalinks set to anything but Plain (WordPress > Settings > Permalinks), so the REST API is
served at
/wp-json/. - WooCommerce 9.8 or later for resending order emails. Everything else uses REST API v3, which every current WooCommerce release serves.
- Zendesk can reach the store. Requests come from Zendesk's servers, not the agent's browser.
If a security plugin, Cloudflare rule or the host's firewall blocks unknown servers, allow
Zendesk's IP ranges (Zendesk's article "Configuring your firewall for use with Zendesk",
https://support.zendesk.com/hc/en-us/articles/4408842860186) or the
/wp-json/wc/path. - The Authorization header reaches WordPress. Some Apache setups (PHP as CGI or FastCGI) drop
it, and WooCommerce then answers as if no key was sent. Add this line to the site's
.htaccess, above the WordPress rules, or ask the host to pass the header through:SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
Nothing is installed in WordPress.
3. Install and connect
- In the Zendesk Marketplace, open Basketwell 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 domain: the domain only, in lowercase, for example
shop.example.com(nohttps://, no path, no port). Basketwell's manifest tells Zendesk to send the secret only to the domain in this setting, so it has to match the store's address exactly. - WordPress path: only if WordPress lives in a sub-folder, for example
/shopforhttps://example.com/shop/. Leave empty otherwise. - Consumer key and Consumer secret: paste both. Zendesk stores the secret as a secure setting: it is never sent to agents' browsers.
- Save. Open any ticket whose requester has ordered from the store.
4. Settings
- Several stores: fill in the domain, keys and name for store 2 and 3. Brands for this store takes Zendesk brand ids (Admin Center > Account > Brand management; the id is in the brand's URL). A ticket opens the store that lists its brand, otherwise the store with no brand list, otherwise store 1. Agents can switch stores in the sidebar.
- Who may take actions:
admin(default),agent(everyone), custom role ids (Admin Center > People > Roles; the id is in the role's URL) orgroup:<id>, separated by commas. Everyone else sees orders read-only. Example:admin, group:360004512345. - Allow refunds, Allow order status changes, Allow resending order emails, Allow order notes: turn each action type on or off for everyone.
- Largest refund without an admin: in the order's currency (100 means $100.00 or 100 euros). Admins have no limit. 0 removes the limit.
- User field with the WooCommerce customer id: the key of a Zendesk user field (Admin Center > People > User fields) that holds the WooCommerce customer id. Use it when customers write in from an address that is not on their store account. Matching by every email on the Zendesk user always runs as well.
5. Using the sidebar
- Matching: Basketwell looks up every email address on the requester's Zendesk profile: store accounts with that address and their orders, plus guest orders whose billing email is exactly that address. Orders that only mention the address somewhere else (a gift note, for example) are left out.
- The customer card: lifetime value and average order (paid orders, net of refunds, per currency), customer since, open orders and refunded totals. "(last N orders)" under the value means the customer has more orders than the sidebar reads, so the value is a minimum.
- An order: click it to see items with SKUs, totals with discounts and coupons, payment, shipping method and address, refunds with reasons, tracking, the customer's checkout note and the order notes. Open in WooCommerce opens it in the store's admin.
- Tracking comes from the Shipment Tracking data on the order (WooCommerce Shipment Tracking and compatible tracking extensions) and from order notes that mention a tracking number. Links are shown only when the store itself provided them.
- Lookup: type an order number (
1043or#1043) or an email in the box at the bottom.
6. Actions
Each action opens a panel inside the order, states exactly what will happen, and is sent only when the agent clicks the confirm button. Afterwards Basketwell adds an internal note to the ticket and a tag.
| Action | What happens in WooCommerce | Tag |
|---|---|---|
| Refund | A refund for the amount and reason. Send the money back through the gateway asks the order's payment gateway to refund the original payment; Record the refund only is for money returned another way. A full refund makes WooCommerce mark the order Refunded. WooCommerce sends its refund email if it is on. The refund's details carry the Zendesk ticket id. | basketwell_refund |
| Change status | Processing, on hold, completed or cancelled, from the statuses that make sense for the current one. Basketwell never moves an unpaid order to processing or completed and never sets Refunded (use a refund). WooCommerce sends its own status emails and restores stock on cancellation. | basketwell_status |
| Resend an order email | One of the emails WooCommerce offers for that order (order details, processing, completed, on hold, refunded). WooCommerce adds an order note saying it was sent. | basketwell_email |
| Add an order note | A private note, or a note WooCommerce emails to the customer. | basketwell_order_note |
If the store's answer gets lost (a timeout or a server error with no answer), Basketwell never sends the action again on its own. It reads the order again: if the change is there, it reports success and logs it; if not, it says nothing changed and the agent can try again.
7. Troubleshooting
| Message | Fix |
|---|---|
| "did not accept the consumer key and secret" | Generate a new key and paste both values again. |
| "answered as if no key was sent" | The web server drops the Authorization header: see section 2. Also check that the key's user is a shop manager or administrator. |
| "A firewall or security plugin ... blocked Zendesk" or "answered with a web page" | Allow Zendesk's IP ranges or the /wp-json/wc/ path (section 2). |
| "REST API was not found at ..." | Check the store domain and WordPress path, and that permalinks are not Plain. |
| "The WooCommerce API key ... is Read only" | Edit the key in WooCommerce and set Read/Write. |
| "needs WooCommerce 9.8 or later" | Update WooCommerce to resend order emails from Zendesk. |
| "The store domain must be the host name only" | Remove https://, any path and any trailing slash. |
| No orders for the requester | Look the order up by number, add the customer's other address to their Zendesk profile, or use the user field mapping. |
8. Plan and billing
Standard: $15 per Zendesk account per month, for every agent, billed monthly by Zendesk. 14-day trial; Zendesk asks for a card at install and billing starts when the trial ends unless you uninstall. No free plan.
9. Data
Basketwell reads orders only while an agent has the sidebar open, keeps nothing after it closes, has no export and no server, and sends nothing to Great Work. Details: https://greatwork.company/apps/basketwell-for-woocommerce/privacy.
10. Uninstalling
Uninstall in Admin Center > Apps and integrations > Zendesk Support apps. The stored keys are
deleted. Revoke the key in WooCommerce > Settings > Advanced > REST API as well. Internal notes and
basketwell_* tags on tickets stay.
Support: hello@greatwork.company, reply within one business day.