Shopify’s latest developer update introduces a dedicated smsMarketingConsent field on the CustomerPhoneNumber object. This change replaces the legacy flat consent flags with a structured consent model that mirrors WhatsApp’s approach. If you build apps, themes, or custom integrations that handle SMS marketing, this is the most important update to act on right now.
What’s New?
The new smsMarketingConsent field stores consent information as a JSON object, capturing status, timestamp, method (e.g., opt_in via checkout or opt_out via account settings), and source details. The previous boolean fields smsMarketingConsent and smsMarketingConsentUpdatedAt remain for backward compatibility but are officially deprecated. New integrations should read and write to the structured field, while existing ones must plan a migration.
Who Is Affected?
*Developers*: Any app or custom script that queries or writes customer phone data via the Admin API, Storefront API, or GraphQL will need to adopt the new schema.\n*Merchants*: While the UI change is invisible, merchants using third‑party SMS marketing apps will see their consent data become more granular and compliant with regulations such as TCPA and GDPR.
Key Changes to the API
graphql\ntype CustomerPhoneNumber {\n id: ID!\n phoneNumber: String!\n smsMarketingConsent: SmsMarketingConsent \n # Deprecated fields (still readable)\n smsMarketingConsentStatus: Boolean @deprecated\n smsMarketingConsentUpdatedAt: DateTime @deprecated\n}\n\ntype SmsMarketingConsent {\n status: ConsentStatus! # GRANTED or REVOKED\n timestamp: DateTime! # When consent was recorded\n method: ConsentMethod! # CHECKOUT, ACCOUNT_SETTINGS, API\n source: ConsentSource! # APP_NAME, SHOPIFY, THIRD_PARTY\n}\n\nThe field returns a non‑null object only when consent exists. If a customer has never opted in, the field resolves to null.
Migration Path
{ status: "GRANTED", timestamp: <original_updated_at>, method: "API", source: "APP_NAME" }.\n3. Update: Adjust your write mutations to include the smsMarketingConsent object instead of the flat flags.\n4. Test: Use the GraphQL Explorer or a private app to verify that reads return the expected object and that writes persist correctly.\n5. Deprecate: After confirming successful migration, remove any code that references the old fields to avoid future breakages.Implementation Example
Below is a simple GraphQL mutation that records consent when a customer opts‑in at checkout:\ngraphql\nmutation AddSmsConsent($customerId: ID!, $phone: String!, $timestamp: DateTime!) {\n customerUpdate(input: {\n id: $customerId,\n phoneNumbers: [{\n phoneNumber: $phone,\n smsMarketingConsent: {\n status: GRANTED,\n timestamp: $timestamp,\n method: CHECKOUT,\n source: SHOPIFY\n }\n }]\n }) {\n customer { id }\n userErrors { field message }\n }\n}\n\nNotice how the mutation nests the consent object inside the phoneNumbers array, matching the API’s required shape.
Testing and Validation
After deployment, run a query like the one below to ensure consent data is stored correctly:\ngraphql\n{\n customer(id: "gid://shopify/Customer/123456789") {\n phoneNumbers {\n phoneNumber\n smsMarketingConsent {\n status\n timestamp\n method\n source\n }\n }\n }\n}\n\nIf the field returns null, the customer has not provided consent yet – a useful signal for your marketing logic.
Next Steps for Merchants
Merchants don’t need to change anything in the Shopify admin, but they should confirm that any installed SMS marketing apps have updated to the new consent model. Encourage store owners to audit their apps in Settings → Apps and integrations, looking for a recent version release that mentions “smsMarketingConsent”. If an app is still using the deprecated fields, request an update from the developer to stay compliant.
Staying on top of this change now prevents future breakages when Shopify fully removes the old flags later this year. Update your code, test thoroughly, and keep your customers’ consent data clean and auditable.
