Creelwell for Shopware: setup guide and help
Public page: https://greatwork.company/apps/creelwell-for-shopware/docs
Creelwell shows the requester's Shopware 6 orders in the Zendesk ticket sidebar and lets the agents you choose change order, payment and delivery states, refund through Shopware, add internal comments and tracking codes. Every action is confirmed first and logged on the ticket as an internal note.
What you need
- A Shopware 6 shop (6.5 or later recommended; refunds through the API need 6.4.12 or later, the order internal comment needs 6.6 or later) whose Administration is reachable over HTTPS.
- A Zendesk Support plan that allows Marketplace apps, and an admin to install it.
- If your shop only lets in known addresses: Zendesk's public IP ranges. Zendesk's servers make the requests, not your agents' browsers.
1. Create the Creelwell role
In the Shopware Administration, go to Settings > System > Users & permissions > Roles > Create role. Name it "Creelwell".
On the Permissions tab:
| Area | Tick | Why |
|---|---|---|
| Orders | Viewer | Read orders, items, deliveries, payments, refunds |
| Customers | Viewer | Find customer accounts and guest records by email |
| Orders | Editor (only for actions) | State changes, internal comments, tracking codes |
On the Detailed privileges tab, make sure these are ticked (Viewer and Editor tick most of them already):
| Privilege | Needed for |
|---|---|
sales_channel read | Sales channel names in the sidebar |
state_machine_history read | The state history with its comments |
state_machine, state_machine_state read | Offering only the transitions your shop allows |
order_transaction_capture, order_transaction_capture_refund read | Showing what was captured and refunded |
order_transaction_capture_refund create and update | Refunds (only if you allow refunds) |
order_refund.editor (the order refund permission) | Refunds (only if you allow refunds) |
Do not give the role access to integrations, users or roles. Creelwell checks this: if the integration can read integrations, Creelwell treats it as an administrator and will not use it.
For a view-only sidebar, leave out Orders: Editor and the refund privileges, and turn the actions off in the Creelwell settings.
2. Create the integration
Go to Settings > System > Integrations > Add integration:
- Name: "Creelwell for Zendesk".
- Administrator: off.
- Role: Creelwell.
- Copy the Access key ID (starts with SWIA) and the Secret access key. Shopware shows the secret only once; if you lose it, generate a new one on the same integration.
Use an integration, not a sales channel key (SWSC, Store API only) or a user's own key (SWUA, that user's full rights). Creelwell refuses both.
3. Install and fill in the settings
| Setting | What to enter |
|---|---|
| Shop name | Shown in the sidebar and, with several shops, in ticket notes |
| Shop domain | The host your Administration runs on, lowercase, like shop.example.com. No https://, no path |
| Base path | Only if Shopware runs in a sub-folder, like /shop. Never /api or /admin |
| Integration access key ID | From step 2 (SWIA...) |
| Integration secret access key | From step 2. Stored as a Zendesk secure setting |
| Administration URL | Optional, for "Open in Shopware" links. Empty means https://<shop domain>/admin |
| Brands for this shop | Zendesk brand ids (Admin Center > Account > Brand management) whose tickets open this shop first |
| Sales channels per brand | Optional: 360001: <sales channel id>, <sales channel id>; 360002: <sales channel id>. The id is the 32-character code in the Administration address when you open the sales channel |
| Shop 2 and 3 | The same fields for more shops. Leave the domain empty to keep a shop off |
| User field with the Shopware customer number | Optional: the key of a Zendesk user field holding the customer number. Email matching always runs too |
| Who may take actions | admin (default), agent (everyone), custom role ids, or group:<id>, comma separated. Everyone else is read-only |
| Allow state changes, refunds, internal comments, tracking codes | Switch each action on or off |
| Largest refund without an admin | In the order's currency. 0 means no limit for anyone allowed to refund |
Open a ticket from a customer. Their orders show in the sidebar.
How orders are found
Creelwell searches the shop for orders whose buyer email is any of the requester's Zendesk email addresses (Shopware keeps the buyer's email on every order, guest checkouts included), and orders of their customer records, so orders placed before a customer changed their email are found too. Every result is checked again, so an order that is not theirs is never shown. The 25 newest orders are read; the lifetime value then says "last 25 orders". The lookup box finds any order number or email in the shop.
Actions
State changes. Every Shopware order has three states: the order, its payment and each delivery. Creelwell asks Shopware which changes it allows from the current state and offers only those. You choose whether Shopware emails the customer (off by default: Creelwell asks Shopware to skip the state emails; other Flow Builder actions for that state still run) and can save a comment in the order history; Creelwell adds the ticket number and your name to it. Recording a payment as paid by hand moves no money, so it is admin-only. Recording it as refunded also moves no money: use it when you returned the money another way.
Refunds. Creelwell uses Shopware's refund API: it records a refund against the payment's capture and Shopware hands it to the payment method's extension, which sends the money back. This works only for payment methods whose Shopware extension records captures and supports refunds. Invoice, prepayment and cash on delivery do not, and some payment extensions use their own refund screens instead. For those, the sidebar says so and the Refund button is not shown; refund with the provider, then change the payment state to Refunded. If a payment method turns out not to support refunds, Creelwell cancels the refund record it created and tells you no money moved. A provider that declines leaves the refund as failed; a provider that finishes later leaves it in progress. Refunds do not put items back in stock.
Internal comments. A dated line with your name and the ticket number, added below the order's internal comment (Shopware 6.6 and later). Customers never see it.
Tracking codes. Added to the delivery you pick, next to any codes already there. Adding a code does not change the delivery state or email the customer; change the state to Shipped afterwards if you want Shopware's shipping email to include it.
Every action is logged on the ticket as an internal note with the tag creelwell_state,
creelwell_refund, creelwell_comment or creelwell_tracking. If Shopware's answer is lost on
the way, Creelwell reads the order again and only then tells you whether it happened; it never
sends the same action twice.
Security model
- The secret access key is a Zendesk secure setting. It can travel only in the body of the sign-in request, and Zendesk only sends it to the shop domain you entered.
- Shopware answers the sign-in with an access token that lasts 10 minutes (unless you changed
shopware.api.access_token_ttl). That token reaches the browser of agents who open Creelwell and is kept in memory only. It can do exactly what the integration's role allows, which is why the role matters and why Creelwell refuses administrator integrations. - Creelwell's own rules (who may act, the refund limit, admin-only paid by hand) apply in the sidebar. The Shopware role is the hard limit. If only some agents should be able to refund at all, give the integration a role without refunds, or restrict the app to those agents in Zendesk (Admin Center > Apps and integrations > Zendesk Support apps > Creelwell > role and group restrictions).
- To cut access at once, delete the integration in Shopware. Tokens already issued expire within their lifetime.
Troubleshooting
| The sidebar says | Do this |
|---|---|
| "is not an integration access key ID" or "belongs to a sales channel" or "to an Administration user" | Use the access key ID of an integration (SWIA...), step 2 |
| "did not accept the integration's access key ID and secret access key" | The secret was mistyped or regenerated. Generate a new secret on the integration and paste it |
| "has administrator rights, so Creelwell will not use it" | Turn Administrator off on the integration and pick the Creelwell role |
| "is missing a permission this needs (order:update)" | Add the named privilege to the role (step 1). The access key stays the same |
| "has no Shopware Admin API at ..." | Check the shop domain and base path |
| "Zendesk did not send the sign-in request" | The shop domain setting must be exactly the host, lowercase, no https:// |
| "No answer from ... through Zendesk" | The shop is down or blocks Zendesk's IP ranges |
| No orders found | The buyer email differs from the requester's. Use the lookup box, add the address to the Zendesk user, or set up the customer number field |
| No Refund button | The payment has no capture in Shopware (invoice, prepayment, some extensions). The sidebar says so under the order |
| "cannot refund through Shopware's refund API" | The payment extension does not support Shopware refunds. Refund with the provider, then change the payment state to Refunded |
| No actions at all | Your role or group is not in "Who may take actions", the action type is off, or this is a new ticket or a user profile |
Uninstall
Uninstall in Zendesk (Admin Center > Apps and integrations > Zendesk Support apps). This deletes
the stored secret. Delete the integration and the Creelwell role in Shopware too. Creelwell
created nothing else; internal notes and creelwell_* tags on tickets stay.
Support
hello@greatwork.company, reply within one business day. Send the ticket number, the order number and what you expected; never send customer data, secrets or access keys.