Zendesk

The Zendesk app connects your Swell store to Zendesk. Customer accounts become Zendesk users, and each user shows the customer's Swell orders: how many, the total spent, the last order and the most recent ones, with a link to the customer in your Swell dashboard.

The app also opens a Zendesk ticket for the customer when a payment fails, an order is canceled or refunded, or a return is requested, with the order details in an internal note. An action in the dashboard imports the customers you already have.

Nothing is sent to Zendesk while Enabled is off.

Install Zendesk from the Swell App Store, and set it up in your test environment before the live one.

With Sync customer accounts on, each customer account becomes a Zendesk user with these details:

Zendesk finds an existing user by external ID or email, so customers who already have a Zendesk user are updated, not duplicated. Customers who check out as guests have a Swell account too, so they become Zendesk users. The app doesn't change a user's tags.

Account updates are sent only when the email, name, phone or an address changes. The Swell user fields are updated on order events instead.

With Show orders on Zendesk users on, the app fills five custom user fields on each user it syncs. Run Actions > Create user fields once to add them to Zendesk. Fields that don't exist in Zendesk are skipped, and the user is synced without them.

The status is Swell's status value, such as delivery_pending, complete or canceled, and the date is the day the order was created, in UTC.

Links to your Swell dashboard, in Swell customer and in ticket notes, open the environment the record is in: https://<store>.swell.store/admin/... for live records and https://<store>.swell.store/admin/test/... for test records.

The fields are updated when the customer's profile changes, and when one of their orders is placed, paid in full, fully fulfilled, canceled or fully refunded. They need Sync customer accounts on too.

Each setting on the Tickets tab opens a ticket for one event:

Each ticket has:

Each order gets at most one ticket per event, and each return one ticket. A second failed payment on the same order doesn't open another ticket. Tickets open only for events that happen while the setting is on.

The ticket starts with an internal note, so the app doesn't email the customer. Zendesk triggers that act on new tickets still run, and depending on its conditions, a trigger that notifies the requester can email the customer. To keep a trigger from running on the app's tickets, add the condition Tags Contains none of the following with swell, or with the tag for the event.

The tags also work in your own Zendesk views, triggers and automations, such as a view of swell_payment_failed tickets.

The link to each ticket is saved on the record it's for. Each order gets a Zendesk tab with Payment failed ticket, Cancellation ticket, Refund ticket and Return tickets. Returns have no page of their own in the dashboard, so a return's ticket link is saved on the return, and Return tickets lists the tickets of all the order's returns, oldest first, one per line with the return number and the link, such as R100001: https://acme.zendesk.com/agent/tickets/52. Every ticket's note links back to the order.

The list is rebuilt from the order's returns when a return ticket is created and when one of the order's returns is updated, while Return requested is on. Rebuilding it doesn't call Zendesk. A return ticket created by an earlier version of the app is listed once its return is updated or another return of the order gets a ticket.

A record that already has a link for an event gets no second ticket for it, so to open a new ticket for the same event, create it in Zendesk.

To create Zendesk users for the customers you already have, go to Apps > Zendesk, choose Actions > Import existing customers, and click Start import.

Import existing customers is in the Actions menu only while Sync customer accounts is on, and Create user fields only while Show orders on Zendesk users is on.

Settings are in Apps > Zendesk > Settings and are saved separately for each environment.

Zendesk subdomain, OAuth client identifier, OAuth client secret and Enabled are at the top. The other settings are on the Customers and Tickets tabs.

Test connection and Create user fields show their messages in the dashboard. The import's messages are on its run: open it on the app's Workflows tab. The app also logs each user it syncs, each ticket it creates and each error. In the Swell dashboard, the logs are under Developer > Console > Logs.

A connection setting is empty, and the message names it. Fill it in, click Save settings, and try again.

Zendesk subdomain has a value that isn't a Zendesk subdomain, such as a custom help-center domain. The message starts with the value, and goes on "Enter the first part of your Zendesk address, e.g. acme for acme.zendesk.com; a custom help-center domain can't be used." Until it's fixed, the app sends nothing to Zendesk. Enter only the acme of acme.zendesk.com, click Save settings, and try again.

Copy the Identifier again from Admin Center > Apps and integrations > APIs > OAuth clients in Zendesk, and check that the client's Client kind is Confidential. Zendesk shows the secret only once, so if you don't have it, add a new client. Paste both, click Save settings, and test again.

The OAuth client is public. Set its Client kind to Confidential in Zendesk, or add a confidential client.

The message names the call Zendesk refused. Check that the OAuth client belongs to a Zendesk admin, and that Zendesk IP restrictions are off. Swell has no fixed IP addresses to allow.

Check Zendesk subdomain. Enter only the acme part of acme.zendesk.com.

No Zendesk account answers at that address. Check Zendesk subdomain for typos.

The app asks for read and write access. Check the OAuth client in Zendesk Admin Center, or add a new confidential client.

Zendesk couldn't be reached, rate-limited the app or had a server error. The reason follows the message. Try again in a minute.

Zendesk answered with another error. The reason and the refused call follow the message.

Create the OAuth client again while signed in to Zendesk as an admin, and enter its identifier and secret.

Create the OAuth client again while signed in to Zendesk as an admin, enter its identifier and secret, and run Create user fields again.

Turn on Enabled, click Save settings, and run Create user fields again.

Check that Enabled and Sync customer accounts are on, and click Save settings. The logs show "Zendesk: missing" followed by the setting when a connection setting is empty, and "isn't a Zendesk subdomain" when Zendesk subdomain can't be used. Account updates are sent only when the email, name, phone or an address changes. Customers who existed before you set up the app are added when you run Import existing customers.

Run Test connection: it lists the user fields missing in Zendesk. Run Create user fields to add them, and check that Show orders on Zendesk users is on. Each user's fields are filled at the customer's next profile change or order event, or when you run the import.

Users synced and tickets created before version 1.0.4 of the app link to your store's address without /admin. A user's Swell customer link is corrected at the customer's next profile change or order event, or when you run the import. Ticket notes keep the link they were created with.

Check that the event's setting is on in the Tickets tab. The logs show "already created" when the order or return has a ticket link for the event, and "skipped, no customer email" when the order's customer has no email. Refund tickets open only for full refunds.

When Zendesk refuses the ticket, the logs show "Zendesk:" with the event and order, then "failed:" and Zendesk's reason. Check the Group ID and Ticket tags against your Zendesk account.

The app's tickets start with an internal note, so the email came from a Zendesk trigger. Add the condition Tags Contains none of the following with swell to the trigger. See Internal notes and Zendesk triggers above.

The run fails without sending anyone, with "Import not started: the Zendesk app is turned off in its settings." when Enabled is off, "Import not started: Sync customer accounts is off in the app settings.", "Import not started: add the … in Apps → Zendesk." when a connection setting is empty, or "Import not started:" followed by "… isn't a Zendesk subdomain. …" when Zendesk subdomain can't be used. Fix the setting, click Save settings, and run the import again.

Enabled or Sync customer accounts was turned off, a connection setting was cleared, or Zendesk subdomain was changed to one that isn't valid, while the import was running. The message gives the reason and the totals until then, such as "Import stopped: the app was turned off in its settings. Before stopping: created 100, updated 0, skipped 0, failed 0, still processing 0." Fix the setting and run the import again. Customers already sent are updated, not duplicated.

Zendesk refused the import, for example because of a rejected OAuth client or a 403. The message gives the same explanation as Test connection and the totals until then. Fix the cause and run the import again.

On temporary errors, such as when Zendesk can't be reached, rate-limits the app or has a server error, each group of 100 customers is tried up to 5 more times before the import fails. Open the run on the Workflows tab to see the step that failed.

Zendesk was still running the bulk job when the import stopped checking it, after about 2 minutes or because a setting changed. Zendesk finishes the job on its own. Search for a few of the customers in Zendesk to check.

Import existing customers needs Sync customer accounts on, and Create user fields needs Show orders on Zendesk users on. Turn the setting on and click Save settings.

Uninstalling the app stops syncing customers, updating the Swell user fields and opening tickets. It removes the app's functions and settings, including the OAuth client secret, the Zendesk tab on orders, and the Test connection, Create user fields and Import existing customers actions. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

The ticket links saved on orders and returns are kept, and the order's links show again on its Zendesk tab if you reinstall. Users, the Swell user fields with their last values, and tickets stay in Zendesk, and the Swell customer fields and ticket notes keep their links to your Swell dashboard.

The app isn't notified when it's uninstalled. If you no longer need the OAuth client, delete it in Zendesk under Admin Center > Apps and integrations > APIs > OAuth clients. To remove the Swell user fields, delete them under Admin Center > People > Configuration > User fields. To pause the app without uninstalling it, turn off Enabled.

The app adds zendesk_ticket_payment_failed, zendesk_ticket_canceled, zendesk_ticket_refunded and zendesk_ticket_return to orders and zendesk_ticket to returns, under $app.zendesk. The ticket fields hold the ticket's agent URL, https://{subdomain}.zendesk.com/agent/tickets/{id}. zendesk_ticket_return holds one <return number>: <link> line for each of the order's returns with a zendesk_ticket, from GET /returns with where[order_id], sorted by date_created and limited to 100. It's rebuilt after each new return ticket, with the new link included even if saving it on the return failed, and on return.updated, and written only when it changes. Only the return's zendesk_ticket keeps a second ticket from opening for the return. The order fields are shown on the order's Zendesk tab, and returns have no tab.

Dashboard links, in swell_customer_url and the ticket note, are built from the request's store.admin_url, the store's address without /admin, or from https://{store.id}.swell.store when it's missing, plus /admin. Functions in the test environment get the Swell-Env: test header, and their links use /admin/test. Workflow requests have no headers and no store.admin_url, so start-import passes the environment as env in the run's data, and the import uses it only when workflow.trigger is function.

Settings are read from zendesk in the app settings, with defaults for values not saved yet. The subdomain accepts acme, acme.zendesk.com or https://acme.zendesk.com/. An empty value counts as missing. A value that isn't a single DNS label after that, such as help.acme.com, is reported as not a Zendesk subdomain by Test connection, Create user fields and the import, and logged by the event functions, which then send nothing. Tags are lowercased, spaces become underscores, and duplicates are dropped. A Group ID that isn't a positive whole number is ignored. Every function except test-connection and start-import stops when enabled is false. start-import doesn't read the settings, and the run it starts fails at its first step instead.

Each function run and workflow step gets a new access token with the client credentials grant: POST https://{subdomain}.zendesk.com/oauth/tokens with grant_type: client_credentials, client_id, client_secret, scope: "read write" and expires_in: 1800. There's no refresh token, and the token isn't stored. The workflow's step output holds only flags, counts, IDs and messages, never the secret or a token.

Calls go to https://{subdomain}.zendesk.com with a bearer token:

Ticket functions check the record for a saved link before getting a token. The note leaves out the order status and timestamps, so a retried request sends the same body, and within Zendesk's 2-hour idempotency window Zendesk returns the ticket it already created. If saving the link fails, the error is logged and the function succeeds, so Swell doesn't retry it. A ticket request looks like this:

{
  "ticket": {
    "subject": "Payment failed for order #1042",
    "comment": {
      "body": "Payment failed for order #1042.\n\nCustomer: Maya Patel <maya.patel@example.com>\nOrder: #1042 · 128.00 USD · 2026-10-01\n\nItems:\n- 1 × Oak Desk Lamp\n\nSwell order: https://alderco.swell.store/admin/orders/6acc9e5f3b1d2a0012f4c771",
      "public": false
    },
    "requester": { "name": "Maya Patel", "email": "maya.patel@example.com" },
    "priority": "normal",
    "tags": ["swell", "swell_payment_failed"],
    "external_id": "swell-payment_failed-6acc9e5f3b1d2a0012f4c771"
  }
}

Phone numbers are parsed with libphonenumber-js's parsePhoneNumberWithError, using the account's phone, then shipping.phone, then billing.phone, with shipping.country or billing.country as the default country. Numbers that fail to parse or isValid() are dropped, and the rest are sent as E.164.

The import reads accounts sorted by id, with an id $gt cursor, and reads recent orders for 10 accounts at a time. Each page is one create_or_update_many job, Zendesk's limit of 100 users. On a 400, 403 or 422 response, the page is sent with create_or_update, 3 users at a time, counting 201 as created, 200 as updated and rejected users as failed. After each job, the workflow sleeps 10 seconds and checks the job status, up to 12 times. Each page and each check reads the settings first, and the run stops without a Zendesk call when enabled is false, a connection setting is missing or the subdomain isn't valid, and before a page when sync_customers is false. Users of a job still running count as pending, and users a finished job doesn't report on count as failed.

Page and job steps are retried on network errors, 429, 5xx and Swell API errors. Other Zendesk errors are returned instead of thrown, so the run fails right away. The workflow returns created, updated, skipped, failed and pending. The import sends swell_customer_url like the event functions, built from store.id.

In the event functions, network errors, 429 and 5xx responses are rethrown, so Swell retries the function. Other errors are logged with console.error, with the refused call, and the function succeeds.

Swell builds and maintains the Zendesk app. For help with the app, email support@swell.is. For questions about your Zendesk account, users, triggers or tickets, contact Zendesk.