Developer guide: custom buttons and app proxy API

Developers can hide the default storefront buttons and build custom UI that talks to the app through Shopify app proxy endpoints.

Hide the default buttons

Use theme app block settings or theme CSS to hide the default wishlist and notify buttons. Keep the app block or embed available if you still rely on its script, visitor token handling, or styles. For a fully custom implementation, call the app proxy endpoints directly.

App proxy base path

Storefront requests use the app proxy path:

/apps/back-in-stock

Shopify signs and forwards these requests to the app. Do not call the app server URL directly from the storefront.

Get widget configuration

GET /apps/back-in-stock/config?variantId=44205181141052&visitorToken=optional-existing-token

Response fields include enabled, channels, wishlist, wishlistSaved, wishlistItemCount, wishlistPageLink, preorder, preorderRule, vapidPublicKey, and visitorToken. Save the returned visitor token in localStorage and reuse it.

Create an email restock signup

POST /apps/back-in-stock/subscribe
Content-Type: multipart/form-data

email=shopper@example.com
productId=8886225764412
variantId=44205181141052
productTitle=Bluetooth Earbuds
variantTitle=Default Title
productHandle=bluetooth-earbuds
locale=en
visitorToken=TOKEN_FROM_CONFIG

A successful response is {"ok":true}. Validation errors return a JSON error message.

Add or remove wishlist items

POST /apps/back-in-stock/wishlist
Content-Type: multipart/form-data

intent=add
visitorToken=TOKEN_FROM_CONFIG
productId=8886225764412
variantId=44205181141052
productTitle=Bluetooth Earbuds
variantTitle=Default Title
productHandle=bluetooth-earbuds
email=optional@example.com

Use intent=remove with variantId to remove one item. Use intent=delete-all to clear the wishlist for the visitor token.

Read the wishlist as JSON

GET /apps/back-in-stock/wishlist?format=json&visitorToken=TOKEN_FROM_CONFIG

The JSON response includes enabled, count, and an items array with product title, variant title, product URL, image, price, availability, and saved time.

Register browser push

POST /apps/back-in-stock/push
Content-Type: multipart/form-data

productId=8886225764412
variantId=44205181141052
productTitle=Bluetooth Earbuds
variantTitle=Default Title
productHandle=bluetooth-earbuds
locale=en
visitorToken=TOKEN_FROM_CONFIG
pushSubscription={...JSON subscription from PushManager.subscribe()}

Implementation notes

  • Always use app proxy URLs on the storefront.
  • Always reuse the signed visitor token returned by the config endpoint.
  • Do not forge Shopify app proxy signatures.
  • Handle 403, 422, and 429 responses in custom UI.
  • Use Shopify variant IDs from the active selected variant.
  • When replacing the default UI, keep accessibility states, focus handling, success messages, and error messages.
Back to blog