Skip to content

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:

MetafieldTypeWritten by
custom.pet_namesingle_line_text_fieldExtension (Customer Account API)
custom.pet_speciessingle_line_text_fieldExtension, dog or cat
custom.pet_breedsingle_line_text_fieldExtension
custom.pet_birthdaydateExtension
custom.pet_photo_urlurlVercel 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:

StoreShop domainApp record config in the repo
Antelope Petsantelopepets.myshopify.comshopify.app.antelope.toml ("Antelope Pet Profile")
Super Snoutssupersnoutshempcompany.myshopify.comNone
My Perfect Petmyperfectpetfood.myshopify.comNone
Bocce's Bakeryboccesbakery.myshopify.comNone

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:

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}
PieceWhere
"My pet" cardextensions/pet-profile/src/PetProfileBlock.tsx (+ api.ts, photo.ts, schema.ts, config.ts)
App Home (admin)extensions/app-home/src/AppHome.tsx
Functionsapi/pet-photo/stage.ts, api/pet-photo/finalize.ts, api/webhooks/*.ts (5 functions)
Shared codelib/: session-token verification, client-credentials Admin tokens, SHOP_CONFIG parsing, Shopify Files helpers
Schemalib/pet-profile.ts, mirrored by hand in extensions/pet-profile/src/schema.ts. Change one, change the other.
Backend URLAPP_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 ​

TopicBehaviour
customers/redactDeletes the customer's photo files (by pet-<customerId>- prefix), then the metafields. Re-throws on failure so Shopify retries.
shop/redactAcknowledges only. The data is the merchant's.
customers/data_requestAcknowledges only. Everything is already on the customer record.

Where it's deployed ​

Repositorygithub.com/crupko93/pet-profile, branch main
Shopify app recordsOne 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.
Extensionspet-profile (customer account) and app-home (admin), API version 2026-07
VercelProject 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.
DatabaseNone

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 ​

  1. Settings → Customer accounts must be set to Customer accounts (new), not classic.
  2. Install the app from the custom distribution link.
  3. Open it from Apps. The App Home page lists the five fields. Press Create definitions.
  4. 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_url doesn't.
  5. 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 inShips withCommand
api/, lib/ (functions)VercelPush/merge to main. One deployment serves every store.
extensions/ (card, App Home)Shopifyshopify app deploy --config <store> for every store's app record
shell
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
done

The 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 ​

WhereVariableNotes
Vercel (Production)SHOP_CONFIGJSON 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:pushSHOP, ADMIN_CLIENT_ID, ADMIN_CLIENT_SECRETCreates the metafield definitions from the command line (-- --dry-run first)

Other scripts ​

ScriptWhat 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 ​

  1. Create the app record in the store's organization (custom distribution, Protected Customer Data Level 1), link it and copy scopes/webhooks.
  2. If the organization has no Pet profile backend internal app, create one there and install it on the store.
  3. Add the store to SHOP_CONFIG in Vercel and redeploy.
  4. shopify app deploy --config <store>, install, then follow the merchant setup above.

Testing ​

  1. Log in to the storefront as a test customer → Profile → the My pet card renders.
  2. Fill everything → Save → reload: values persist. Cross-check under Customers → the customer → Metafields.
  3. 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.
  4. Clear a field → Save → reload: it stays cleared.
  5. Negative test: set a definition's customer-account access to read-only and confirm the card shows the error instead of failing silently.
  6. 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 ​

SymptomCause
Access denied for customer fieldThe 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 allowedDefinitions missing, or without customer-account read/write.
Failed to fetch / CORS error on photo upload onlyAPP_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 failedThe internal app isn't installed on that store, or belongs to a different organization.
Block missing in the customer accounts editorA 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 deploy per release.
  • Photos live in Content → Files next to marketing assets. The filename prefix keeps them identifiable, but the library gets noisy at scale.

Antelope Themes Documentation

Enter the password to access this site.