Paketwell for Billbee: setup and help
Paketwell shows your customer's Billbee orders (shop, Amazon, eBay, Otto, Kaufland and manual orders) next to their Zendesk ticket, in German, English, French or Italian, and lets the agents you choose add an internal comment to an order or change its state, with every action logged on the ticket. $9 per agent per month after a 14-day trial.
What you need
- Zendesk Support (any plan that allows Marketplace apps) and admin access to install.
- A Billbee account with the API switched on, an API password, and your own Billbee API key.
Billbee API access (three values)
-
Username: the email you log in to Billbee with.
-
API password: Billbee > Settings > API: switch the API on and set an API password. It is separate from your login password.
-
API key: Billbee issues API keys on request. Use the API key form linked in Billbee's API documentation (app.billbee.io/swagger) or write to Billbee support. Text you can send:
Hallo Billbee-Team, wir möchten die Billbee-API mit unserem eigenen Konto nutzen, um Bestellungen in unserem Kundenservice (Zendesk, App "Paketwell for Billbee") anzuzeigen. Bitte stellt uns dafür einen API-Schlüssel aus. Benutzername:
. Danke! (English: "Hello Billbee team, we want to use the Billbee API with our own account to show orders in our customer service (Zendesk, app "Paketwell for Billbee"). Please issue us an API key. Username: ... Thanks!")
Paketwell stores the API password and API key as Zendesk secure settings: agents never see
them, the browser never receives them, and Zendesk's proxy only sends them to app.billbee.io (the
key in the X-Billbee-Api-Key header, the password as HTTP Basic auth). Great Work never receives
them either.
Install
Follow the installation guide on the listing: enter the three values, then choose who may act.
How orders are matched
- Every email on the requester's Zendesk profile (up to five) is searched in Billbee's customers. Each customer found is read and kept only when one of its emails is exactly one of theirs.
- Marketplaces hide buyer emails behind relay addresses (marketplace.amazon.de, members.ebay.de) or send none. A Billbee customer with only such an email and exactly the requester's full name (umlauts and accents ignored: Müller = Mueller) is shown with a "Marketplace, matched by name" badge. If more than two such customers share the name, none is shown and a warning says so.
- Order numbers written in the ticket subject or first message are read too: numbers after "#", "Bestellung", "Bestellnummer", "Auftrag", "order", "commande" or "ordine", Amazon numbers (123-1234567-1234567) and eBay numbers (12-12345-12345). An order with a relay or missing email is shown when the buyer's full name or phone matches the requester, with a badge.
- Anything else the ticket names is listed by number with a masked email, never shown. An agent can look it up on purpose.
Each customer shows their newest 10 orders. The lookup box takes an order number (shop or marketplace), an invoice number, an email or a full name.
Actions
| Action | Setting | Default | What happens |
|---|---|---|---|
| Add order comment | Allow order comments | On | An internal comment is added to the order in Billbee, signed "Zendesk: |
| Change state | Allow state changes + States agents may set | Off | The order moves to the chosen state. Billbee may pass it to the shop or marketplace and run your rules |
Each action is confirmed first, checked against a fresh read of the order (nothing is sent if
someone changed the state meanwhile or the order is archived), sent once, read back, and logged as
an internal note with a paketwell_comment or paketwell_state tag. If Billbee's answer is lost,
Paketwell reads the order again (finding the comment by its reference) instead of sending twice.
States agents may set: numbers or English or German names, comma separated: ordered/bestellt (1), confirmed/bestätigt (2), paid/bezahlt (3), shipped/versendet (4), complaint/reklamation (5), closed/abgeschlossen (7), canceled/storniert (8), mahnung (11), 2. mahnung (12), packed/gepackt (13), offered/angeboten (14), zahlungserinnerung (15), im fulfillment (16). Empty means all of these. Deleted (6) and archived (9) are never offered.
Who may act: "admin" (default), "agent" (everyone), custom role ids, or "group:
The API limit
Billbee allows 2 requests a second per endpoint for each login (and 10 a second in total), shared with every integration on that login. Paketwell spaces its calls about half a second apart. A sidebar reads one search and one customer read per email, one name search, one order list per matched customer, and one read per order number in the ticket; full orders load only when an agent opens one. A refused read is retried once after Billbee's wait time; a write is never repeated.
Troubleshooting
| Message | Fix |
|---|---|
| Billbee did not accept the API key | Paste the key Billbee issued (not the API password); request one if you have none |
| Billbee did not accept the username and API password | Use the login email and the API password from Settings > API; switch the API on |
| Billbee's rate limit is used up | Wait a few seconds; other integrations on the same login share the limit |
| No orders for this requester | Their Billbee email differs (marketplace relay); look the order up by number |
| Change state not offered | Turn on "Allow state changes" and list the states |
| This order is archived in Billbee | Restore it in Billbee before changing it |
Uninstall
Uninstalling removes the app and its settings, including the API key and password. Paketwell
created nothing in Zendesk; the paketwell_* tags stay on past tickets and the comments stay on the
Billbee orders.
Support: hello@greatwork.company, reply within 1 business day.