How to Maintain a Custom Shopify App: Routine and Handover

A custom Shopify app is never really finished. The first version ships, the team starts relying on it, and from then on the app sits in the middle of things that keep moving: Shopify’s API versions, its platform, your hosting, the libraries the code uses, and the people who know how it works.

Most custom apps fail because nobody owned the upkeep, not because the code was bad. This guide lists what that upkeep involves, gives you a routine you can put in a calendar, and ends with a checklist for when the app changes hands.

What needs looking after

Area	Why it needs attention	How often
API versions	Each version is supported for at least 12 months	Every quarter
Webhooks	Failed deliveries are retried, then subscriptions can be removed	Watch daily, review monthly
Monitoring and logs	Quiet failures look like success	Daily alerts, monthly review
Hosting	The app runs on servers someone pays for and patches	Monthly
Secrets and tokens	Credentials leak, people leave	On every team change, and regularly
Dependencies	Libraries get security fixes and breaking releases	Monthly
Shopify platform changes	Features are retired and data moves	Monthly scan, act by the deadline
Documentation	The next person needs to run it	On every change

API versions

Shopify releases a new API version every three months and supports each stable version for at least 12 months. When an app keeps calling a version that is no longer accessible, Shopify answers with the oldest accessible stable version instead, so the app runs on a version it was never tested against.

Shopify recommends updating to the latest stable version each quarter. Our API version upgrade checklist walks through finding the version you call, reading the release notes, testing and deploying. If the app still uses the REST Admin API, which Shopify has called legacy since October 1, 2024, add the REST to GraphQL migration to the plan.

One rule from the versioning docs is easy to miss: do not use an app’s access token outside that app. Deprecated calls are attributed to the app whose token made them, so a spreadsheet script borrowing the token can trigger warnings that point at the wrong code.

Webhooks and retries

Shopify’s HTTPS webhook docs set the limits your handler has to live within:

a one-second connection timeout and five seconds for the whole request;
8 retries over the next 4 hours when a delivery fails;
subscriptions created through the Admin API are removed after 8 consecutive failures, with warning emails to the app’s emergency developer email.

The webhook best practices add that delivery isn’t always guaranteed and order isn’t guaranteed either. A maintained app therefore has three habits:

Verify and dedupe. Check the X-Shopify-Hmac-Sha256 signature and skip repeats using X-Shopify-Webhook-Id.
Answer fast, work later. Accept the request, put the job in a queue, and respond within the timeout.
Reconcile. A scheduled job fetches what changed since the last run, using updated_at, and fixes what webhooks missed.

Our integrations that don’t break checklist goes deeper on each.

Monitoring and logs

For apps managed in the Dev Dashboard, Shopify provides monitoring you should look at, not just have:

Alerts for deprecated API calls, webhook failures, Function errors and extensions pinned to an unsupported API version. The webhook failures alert is marked critical and fires when more than 0.5% of deliveries fail across at least 500 deliveries in 24 hours.
An Overview with Admin API calls, webhook deliveries and Function runs, including GraphQL and REST error rates.
Logs of individual requests and deliveries, kept for 30 days, with up to 7 days in one view.

Shopify’s logs show what happened between Shopify and the app. Your own logs need to show what the app did next. At minimum, record:

when each scheduled job last finished successfully;
every record the app skipped or failed, with the reason;
a daily total on both sides, such as orders synced or stock units updated.

Send failures to wherever the team already looks. A sync that stopped on Friday should not be found on Monday.

Hosting

A custom app runs on servers you or someone else pays for. Write down:

where it runs, under whose account, and who receives the bill;
how it is deployed, ideally with one documented command or pipeline rather than steps in someone’s head;
how to roll back to the previous version;
where the data lives, how it is backed up, and whether anyone has tested restoring it;
the domains and certificates the app uses, and when they renew.

If the hosting account is in a former developer’s name, move it first.

Secrets and tokens

A custom app holds credentials that can read and change your store. Treat them that way:

Keep secrets out of the code. Store the client secret and any tokens in your hosting provider’s secret store or a password manager you control.
Know which token type you have. Apps created in the Dev Dashboard request tokens with code; the client credentials grant, for example, returns a token that lasts 24 hours, so the app must refresh it. Legacy apps created in the admin have a token that was shown once, and their API key and secret cannot be rotated.
Rotate when people leave. Shopify recommends rotating the client secret if it was exposed, if someone with access left your organization, or as regular hygiene. Update the app and every stored token before you revoke the old secret.
Review scopes. Remove access the app no longer uses. Each scope is one more thing a leaked credential can do.

Dependency updates

The app’s libraries ship security fixes, and occasionally breaking changes.

Check for updates monthly and apply security fixes promptly.
Update one major version at a time, with tests run after each.
Keep the runtime version, such as Node.js or Python, within its supported releases.
Prefer Shopify’s official libraries where they fit; the versioning docs note that they handle version configuration for you.

Shopify platform changes

Shopify retires and replaces parts of its platform on a schedule, and some changes reach custom apps directly. Recent examples:

Shopify Scripts ended on June 30, 2026. Scripts still published were deactivated; their logic moves to Shopify Functions. See Shopify’s migration guide and our Scripts to Functions migration guide.
Market-driven shipping is rolling out. Shipping settings move from delivery profiles into Markets; the rollout started October 1, 2026 and every merchant moves by July 1, 2027. On those stores, merchant-owned delivery profile APIs are deprecated, and writes can appear to succeed without changing the live settings. Our guide to market-driven shipping and custom apps covers what to check.
New custom apps come from the Dev Dashboard. Since January 1, 2026, new custom apps are created in the Dev Dashboard or with Shopify CLI. See creating a custom app in the Dev Dashboard.

Once a month, scan the developer changelog for anything touching the resources your app reads or writes, and put each deadline in the calendar.

A maintenance routine

Every day (automated)

Alerts for failed jobs, webhook failures and error spikes reach a named person.
The reconciliation job runs and reports what it fixed.

Every month (about an hour)

Review Dev Dashboard alerts and the app’s own error log.
Compare daily totals on both sides for the month.
Apply dependency security updates.
Scan the developer changelog for changes that touch your app.
Check hosting bills, certificates and backups.

Every quarter

Run the API version upgrade checklist.
Review access scopes and who can reach the Dev Dashboard and hosting.
Test a restore from backup.
Update the runbook.

Every year

Rotate the client secret, following Shopify’s rotation steps.
Ask whether the app still does a job worth doing, or whether Flow or a public app now covers it.

Who owns what

Write the answers down before you need them:

Question	Answer to record
Who owns the code repository?	An account in your company’s name
Who owns the app in the Dev Dashboard?	Your organization; apps belong to the organization
Who owns the hosting and pays for it?	A company account, not a personal one
Who holds the client secret?	Your secret store, with named people who can read it
Who receives Shopify’s developer warnings?	An address someone on your side reads
Who does the monthly and quarterly checks?	A named person or supplier

Handover checklist

Use this when a developer leaves, an agency changes, or the app moves in house:

Code. Repository transferred to your account, with the full history, and the new owner can build and run it locally.
App access. The app lives in your Dev Dashboard organization, and the new team has the App developer role there. Old accounts are removed.
Hosting. The account, billing, domains and certificates are in your name, and the new team can deploy and roll back.
Secrets. Every secret is listed. Rotate the client secret and any other keys the previous team could see.
Data. Databases and backups are listed, and a restore has been tested.
Webhooks. Every subscription is listed with its topic, address and API version.
Jobs. Every scheduled job is listed with when it runs and what it does.
Runbook. How to deploy, roll back, read logs and handle the common failures.
Open issues. Known bugs, pending deprecations and the next API version deadline.
A shadow week. The new owner runs a deploy and a version check while the old one is still reachable.

For a legacy admin-created app, add one more line: confirm the access token is stored safely, since it was shown only once.

Having it looked after

If no one on your side can own this, the upkeep can be handed to a team that does it routinely. Our custom solutions page describes the Shopify work we take on; it is the same team that builds and runs Storefleet Store Ops. To compare options, see what a custom Shopify app costs and hiring a Shopify app developer.

FAQ

How often does a custom Shopify app need updating?

At least once a year for the API version, since each version is supported for at least 12 months, and Shopify recommends updating each quarter. Dependencies and platform changes need a monthly look.

What happens if nobody maintains a custom app?

It often keeps running, which is the problem. Expired API versions fall forward to a newer one the app was not tested on, failing webhooks can lead to removed subscriptions, and deprecated features stop working on Shopify’s schedule.

How do I know if my custom app’s webhooks are failing?

For Dev Dashboard apps, the webhook failures alert and the app’s Logs show failed deliveries. Shopify also emails the app’s emergency developer address when deliveries keep failing, and removes Admin API subscriptions after 8 consecutive failures.

What should I get from a developer when they hand over a custom app?

The code repository, ownership of the app in your Dev Dashboard organization, the hosting account, a list of secrets (then rotate them), webhook and job lists, backups and a runbook.

Should I rotate credentials when a developer leaves?

Yes. Shopify recommends rotating the client secret when someone with access leaves your organization. Update the app and stored tokens before revoking the old secret.