Pet Profile
Overview
Pet Profile adds a "My pet" card to the Profile page of new customer accounts. Customers enter their pet's name, species (dog/cat), breed, birthday and a photo. The values are stored on the Shopify customer record as metafields, so themes (Liquid), Shopify Flow and Klaviyo can read them without going through the app.
Everything is optional. Clearing a field and saving removes the metafield.
The data supports a pet birthday gesture: metafield → Shopify Flow (Customer metafield updated or a scheduled trigger) → Klaviyo profile property → birthday flow. That needs no app change. pet_birthday is a real date for this reason.
Data written
Namespace custom, owner type Customer:
| Metafield | Type | Written by |
|---|---|---|
custom.pet_name | single_line_text_field | Extension (Customer Account API) |
custom.pet_species | single_line_text_field | Extension, dog or cat |
custom.pet_breed | single_line_text_field | Extension |
custom.pet_birthday | date | Extension |
custom.pet_photo_url | url | Vercel functions, after the file upload |
Merchant-owned custom namespace on purpose: $app: metafields are private by default (invisible to Liquid, Flow and the ESP) and can linger after an uninstall.
Photos (JPEG, PNG or WebP, max 5 MB) are uploaded into the store's own Content → Files as pet-<customerId>-<uuid>.<ext>. Uploading a new photo deletes the previous one.
Where it's used
One Vercel deployment serves every store; each store has its own Shopify app record. The repo holds an app record config for Antelope Pets:
| Store | Shop domain | App record config in the repo |
|---|---|---|
| Antelope Pets | antelopepets.myshopify.com | shopify.app.antelope.toml ("Antelope Pet Profile") |
| Super Snouts | supersnoutshempcompany.myshopify.com | None |
| My Perfect Pet | myperfectpetfood.myshopify.com | None |
| Bocce's Bakery | boccesbakery.myshopify.com | None |
A store without a config in the repo is added as described in Adding a store. A development record (shopify.app.antelope-dev.toml) points at dev-store-749237498237499044.myshopify.com.
Theme-side hooks: none. Customer account pages are rendered by Shopify, not by the theme, and no brand theme reads the custom.pet_* metafields. To use them in Liquid:
{{ customer.metafields.custom.pet_name }}
{{ customer.metafields.custom.pet_birthday | date: "%B %-d" }}Architecture
No web server, no OAuth and no database. Name, species, breed and birthday are written straight from the extension to Shopify. Only the photo needs a backend, because the Customer Account API has no file-upload mutation. That backend is a handful of stateless Vercel functions.
Customer account (Shopify-hosted)
└── UI extension "pet-profile" target: customer-account.profile.block.render
├── text/date → Customer Account API (metafieldsSet) — no backend
└── photo, in three hops:
1. POST {APP_URL}/api/pet-photo/stage → staged upload target + signed ticket
2. POST the bytes straight to Shopify's storage (never through Vercel)
3. POST {APP_URL}/api/pet-photo/finalize → fileCreate, then metafieldsSet(pet_photo_url)
Shopify admin
└── UI extension "app-home" target: admin.app.home.render → setup page ("Create definitions")
Shopify compliance webhooks → /api/webhooks/{customers-data-request, customers-redact, shop-redact}| Piece | Where |
|---|---|
| "My pet" card | extensions/pet-profile/src/PetProfileBlock.tsx (+ api.ts, photo.ts, schema.ts, config.ts) |
| App Home (admin) | extensions/app-home/src/AppHome.tsx |
| Functions | api/pet-photo/stage.ts, api/pet-photo/finalize.ts, api/webhooks/*.ts (5 functions) |
| Shared code | lib/: session-token verification, client-credentials Admin tokens, SHOP_CONFIG parsing, Shopify Files helpers |
| Schema | lib/pet-profile.ts, mirrored by hand in extensions/pet-profile/src/schema.ts. Change one, change the other. |
| Backend URL | APP_URL constant in extensions/pet-profile/src/config.ts = https://pet-profile-nine.vercel.app |
How the functions stay stateless:
- Customer identity: the extension sends its session token. The function verifies the signature with the store's app-record secret, so there are no sessions to store.
- Admin API tokens: minted on demand with the client credentials grant from a per-organization internal app ("Pet profile backend"), valid 24 hours.
- Which store? Taken from the signed payload. One Vercel deployment serves every store. Adding a store is an entry in
SHOP_CONFIG, not a new deployment. - Photo bytes go directly to Shopify's staged upload. Vercel caps request bodies at 4.5 MB, below the 5 MB photo limit.
Privacy webhooks
| Topic | Behaviour |
|---|---|
customers/redact | Deletes the customer's photo files (by pet-<customerId>- prefix), then the metafields. Re-throws on failure so Shopify retries. |
shop/redact | Acknowledges only. The data is the merchant's. |
customers/data_request | Acknowledges only. Everything is already on the customer record. |
Where it's deployed
| Repository | github.com/crupko93/pet-profile, branch main |
| Shopify app records | One custom-distribution app record per store (the stores do not share one Plus organization). Antelope: Antelope Pet Profile, client_id a369f83585a7167a400a750f3eabcce9. Dev: 4b650d1f153104e05f6f59642e18373f. |
| Internal apps (token minting) | Pet profile backend, one per Shopify organization: Alpine Pet Holdings LLC (Antelope, Super Snouts, MPP) and Bocce's Bakery. Scopes read_customers, write_customers, read_files, write_files. No distribution. |
| Extensions | pet-profile (customer account) and app-home (admin), API version 2026-07 |
| Vercel | Project pet-profile, no framework, outputDirectory: public, functions api/**/*.ts with maxDuration: 30. Git-connected, production from main. Live at https://pet-profile-nine.vercel.app. No region pinned in vercel.json. |
| Database | None |
Use the production URL
DEPLOYMENT.md uses https://antelope-pet-profile.vercel.app as an example host. That host does not exist. The production deployment is https://pet-profile-nine.vercel.app, which is what config.ts and the webhook URIs use. Running npm run app-url with any other host breaks photo upload and rewrites the webhook URIs in the tomls.
How to use (merchant / admin)
One-time setup per store
- Settings → Customer accounts must be set to Customer accounts (new), not classic.
- Install the app from the custom distribution link.
- Open it from Apps. The App Home page lists the five fields. Press Create definitions.
- If it reports definitions without customer-account access, open each under Settings → Custom data → Customers → definition → Access and set Customer account to Read and write. Four of them need it.
pet_photo_urldoesn't. - Settings → Customer accounts → Customize (customer accounts editor) → Profile page → Add block → Pet profile → Save.
The block has no settings. The card title is "My pet".
The most common failure
"Access to this namespace and key on Metafields for this resource type is not allowed" means step 3 or 4 wasn't done. Since API 2024-07 a customer metafield must have a definition with explicit customer-account access before an extension can read or write it.
What the customer sees
On /account/profile: a My pet card with name, species (dog/cat), breed, birthday and a photo picker, plus a Save button. Validation errors from Shopify (userErrors) are shown in the card.
How to update & deploy
Two things ship independently:
| Change in | Ships with | Command |
|---|---|---|
api/, lib/ (functions) | Vercel | Push/merge to main. One deployment serves every store. |
extensions/ (card, App Home) | Shopify | shopify app deploy --config <store> for every store's app record |
git clone git@github.com:crupko93/pet-profile.git && cd pet-profile
npm install
npm run typecheck # all three tsconfigs
npm run lint
npm run dev # shopify app dev, extensions only, against a dev store
# release the extensions to every store that has a config
for cfg in antelope; do # every shopify.app.<store>.toml in the repo
shopify app deploy --config "$cfg" --force
doneThe repo holds the antelope and antelope-dev configs. Add another store's config with npm run config:link (e.g. shopify app config link --config supersnouts), then copy [access_scopes] and [webhooks] from shopify.app.toml into the generated file. The CLI generates it from the nearly empty remote record.
Environment variables
| Where | Variable | Notes |
|---|---|---|
| Vercel (Production) | SHOP_CONFIG | JSON object keyed by *.myshopify.com domain. Each entry has extensionClientId, extensionSecret (that store's app record) and adminClientId, adminSecret (the organization's internal app). Redeploy after changing it. |
Local, npm run metafields:push | SHOP, ADMIN_CLIENT_ID, ADMIN_CLIENT_SECRET | Creates the metafield definitions from the command line (-- --dry-run first) |
Other scripts
| Script | What it does |
|---|---|
npm run app-url <url> | Rewrites APP_URL in extensions/pet-profile/src/config.ts and the webhook URIs in the tomls. Extensions get no build-time env injection, so this is a committed constant. |
npm run config:use <store> | Switch the active app config |
Adding a store
- Create the app record in the store's organization (custom distribution, Protected Customer Data Level 1), link it and copy scopes/webhooks.
- If the organization has no Pet profile backend internal app, create one there and install it on the store.
- Add the store to
SHOP_CONFIGin Vercel and redeploy. shopify app deploy --config <store>, install, then follow the merchant setup above.
Testing
- Log in to the storefront as a test customer → Profile → the My pet card renders.
- Fill everything → Save → reload: values persist. Cross-check under Customers → the customer → Metafields.
- Upload a photo → it appears in Content → Files as
pet-<customerId>-<uuid>.<ext>and renders after reload. Upload a second one: the first is deleted. - Clear a field → Save → reload: it stays cleared.
- Negative test: set a definition's customer-account access to read-only and confirm the card shows the error instead of failing silently.
- Liquid: the snippet under Where it's used renders the saved values in the theme.
Backend smoke test (read-only): https://pet-profile-nine.vercel.app serves a placeholder page. OPTIONS /api/pet-photo/stage returns 204. A GET returns {"error":"Method not allowed"}.
Troubleshooting & known limits
| Symptom | Cause |
|---|---|
Access denied for customer field | The app record's scopes are missing (generated toml used without copying [access_scopes]). Redeploy, then reinstall. |
Access to this namespace and key on Metafields ... is not allowed | Definitions missing, or without customer-account read/write. |
Failed to fetch / CORS error on photo upload only | APP_URL doesn't point at the live Vercel deployment. npm run app-url https://pet-profile-nine.vercel.app, then redeploy the extensions. |
401 This deployment doesn't serve <shop> | The store isn't in SHOP_CONFIG, or the domain is spelled differently. |
Client credentials grant failed | The internal app isn't installed on that store, or belongs to a different organization. |
| Block missing in the customer accounts editor | A stale dev preview pins the store: shopify app dev clean --store <store>. |
- One pet per customer. Multiple pets would need a metaobject list. Metaobjects can't be written from the Customer Account API, so everything would move through the backend, plus a data migration.
- One app record per store. Each store means its own record, its own Protected Customer Data request, and its own
shopify app deployper release. - Photos live in Content → Files next to marketing assets. The filename prefix keeps them identifiable, but the library gets noisy at scale.