Termwell: setup and user guide

What Termwell does

Termwell shows the requester's Chargebee customer in the Zendesk ticket sidebar (and on user profiles): subscriptions with plan and addons, unpaid invoices and dunning, invoices, credit notes, refunds and credit balances. Agents you allow can refund an invoice, cancel a subscription at the end of the term or remove that, pause or resume it, apply a coupon, add promotional credit, and send a payment link for unpaid invoices. Every action asks for confirmation first and is logged on the ticket as an internal note.

1. Create an API key in Chargebee

In Chargebee: Settings > Configure Chargebee > API Keys > Add API Key. Name it "Termwell for Zendesk". Keys for your test site and your live site are different; use the live site's key in production.

Publishable keys do not work (they cannot read customers). If an agent tries an action with a read-only key, Termwell shows Chargebee's refusal and says which key type is needed; nothing changes in Chargebee.

2. Install and connect

1. In the Zendesk Marketplace, open Termwell 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.
2. Chargebee site name: only the part before .chargebee.com in your Chargebee address. If you sign in at https://acme.chargebee.com, type acme; a test site looks like acme-test. Termwell tells you if you typed the full address instead.
3. Paste the key into Chargebee API key. Zendesk stores it as a secure setting: it is never sent to agents' browsers, and Zendesk only adds it to requests going to the site you named.
4. Save. Open any ticket whose requester is a Chargebee customer.

3. Settings

• Several Chargebee sites: fill in the site name and key for site 2 and 3 (a site turns on once its name is set) and optionally a label. Brands for this site takes Zendesk brand ids (Admin Center > Account > Brand management; the id is in the brand's URL). A ticket opens the site that lists its brand, otherwise the site with no brand list, otherwise site 1. Agents can switch sites 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) or group:<id>, separated by commas. Everyone else sees the sidebar read-only. Example: admin, group:360004512345.
• Allow refunds, Allow subscription changes, Allow coupons and promotional credits, Allow payment links: turn each action type on or off for everyone.
• Largest refund without an admin and Largest promotional credit without an admin: in the invoice's or customer's currency (100 means $100.00 or 100 euros). Admins have no limit. 0 removes the limit.
• Coupons agents may apply: coupon ids, separated by commas. Non-admins can apply only these; admins can apply any active coupon. Leave empty to allow any active coupon.
• Custom refund reason codes: if your site uses its own credit note reason codes (Chargebee Settings > Reason Codes > Credit Notes), list them exactly as written there. The refund form then offers these instead of Chargebee's standard reasons.
• User field with the Chargebee customer id: the key of a Zendesk user field (Admin Center > People > User fields) that holds the Chargebee customer id. Useful when customers write in from a different address than the one in Chargebee.
• Zendesk external id is the Chargebee customer id: turn on when both systems use your own user ids, so a customer is found even if their email differs.

Matching by email always runs: Termwell tries every email address on the requester's Zendesk profile (as written and in lowercase). When several customers match, the sidebar lists them and agents pick one. Agents can also look up a customer by exact email or customer id.

4. Using it

• Sidebar: the customer and their balances (promotional credit, refundable credit, excess payments, unbilled charges), then alerts: unpaid invoices with the total due, dunning in progress with failed attempts and the next retry, and an expired or invalid payment method. Then subscriptions (plan, addons, coupons, status and the next date), the latest invoices (unpaid ones always included), credit notes and refunds.
• Refund: on a paid invoice, click Refund. The amount starts at what can still be refunded online; change it for a partial refund. Pick a reason and click Refund $X. Chargebee creates a refundable credit note and refunds through the original payment. A payment that is still processing cannot be refunded until it settles, and partial refunds need a gateway that supports them.
• Cancel at end of term: the customer keeps access until the term ends and is not billed again. Remove scheduled cancellation undoes it before that date. Subscriptions with a contract term are changed in Chargebee, where the contract options are.
• Pause: at the end of the current term (the default), now, or on a date, with an optional resume date. Resume reactivates a paused subscription now; Remove scheduled pause cancels a pause that has not started. Your site's pause settings apply (the pause feature must be on in Chargebee).
• Apply coupon: type a coupon id or a single-use coupon code and click Look up. Termwell shows the discount and blocks expired coupons, a coupon already on the subscription, or one in another currency.
• Add promotional credit: an amount and a description the customer sees on invoices. Chargebee applies the credit to the next invoices.
• Send a payment link: when the customer has unpaid invoices, Termwell creates a Chargebee payment page (valid 5 days) and adds the link to your reply. Nothing is sent until you submit the reply.
• PDF: opens the invoice PDF (Chargebee's link works for 60 minutes), for example to attach it.
• After each action the ticket gets an internal note, for example: "Termwell (Chargebee): Refunded $29.00 on invoice 1025 for Chargebee customer hb-4471. Reason: service unsatisfactory. Credit note CN-41, refund transaction txn_... (success). Done by Maya Lindqvist from this ticket." and a tag: termwell_refund, termwell_cancel, termwell_cancel_removed, termwell_pause, termwell_resume, termwell_pause_removed, termwell_coupon, termwell_credit or termwell_payment_link. Use the tags in views, triggers and reports.
• Actions are available on tickets only. On a new ticket and on user profiles the sidebar is read-only.

5. Data and security

• The key stays in Zendesk's secure settings and is used only as the Basic authentication user name of requests Zendesk's proxy sends to your own site at yoursite.chargebee.com.
• Termwell has no server. It keeps nothing after the sidebar closes, has no export, and sends nothing to Great Work. Refund comments and promotional credit references carry the Zendesk ticket number and the agent's name in Chargebee.
• Uninstalling deletes the stored keys. Also delete the API key in Chargebee.

6. Troubleshooting

Support: hello@greatwork.company, reply within one business day.