Marketing Preferences

Marketing preferences cover the channels a customer can consent to (email, SMS, post, third-party) and the audit data captured each time consent changes. All consent-changing mutations require an audit payload describing what message was shown to the user and where, so that consent collection is verifiable for compliance.

Availability of individual channels and flows is gated by site features such as MARKETING_PREFERENCES_ENABLED, POSTAL_MARKETING, THIRD_PARTY_MARKETING_SETTINGS, DOUBLE_OPT_IN and DUAL_CONSENT.

Checking preferences before account creation

Use this when collecting an email on a signup form. The response tells you whether the email is already a customer, is already on the newsletter, or is unknown — useful for deciding what consent prompt to show.

query AccountCreationMarketingPreferences {
  accountCreationMarketingPreferences(email: "shopper@example.com")
}

Reading the logged-in customer’s preferences

A single boolean per marketing type. Query each type the site supports.

query CustomerMarketingPreferences {
  customer {
    email: marketingPreferences(type: EMAIL)
    sms: marketingPreferences(type: SMS)
  }
}

For sites that use OneTrust to manage dual consent (cookies and marketing together), the customer also exposes the URL to send the customer to:

query DualConsentUrl {
  customer {
    dualConsentOneTrustUrl
  }
}

Updating preferences for a logged-in customer

Audit data is required. Provide the exact message the customer saw, an identifier for the form, and the location on the site. If the channel can’t be enabled (for example signing up for SMS when there’s no phone number on the account), the response surfaces INSUFFICIENT_DATA.

mutation UpdateMarketingPreferences {
  updateMarketingPreferences(
    input: {
      type: EMAIL
      newValue: true
      auditData: {
        messageShown: "Sign up for emails to receive marketing about offers and promotions"
        formIdentifier: "AccountSettings"
        formLocation: "/account/marketing-preferences"
      }
    }
  ) {
    error
  }
}

Signing up without an account

For footer newsletter forms and similar surfaces where the user is not logged in. The mutation is rate limited. contactDetails is the email or phone number depending on type; for SMS, pass emailAddress as well so the SMS sign-up can be linked to any existing email sign-up record.

mutation SignUpForMarketing {
  signUpForMarketing(
    input: {
      type: EMAIL
      contactDetails: "shopper@example.com"
      auditData: {
        messageShown: "Get 10% off your first order when you sign up to our newsletter"
        formIdentifier: "FooterNewsletter"
        formLocation: "/"
      }
    }
  )
}

Possible results are OK, DUPLICATE, REQUIRES_VERIFICATION (double opt-in flows), NOT_FOUND and UNKNOWN_ERROR.

Confirming a double opt-in

When DOUBLE_OPT_IN is enabled, sign-ups produce REQUIRES_VERIFICATION and an email goes out with a confirmation link. The link carries the token and a hashed email; pass them straight through.

mutation ConfirmMarketing {
  confirmMarketing(
    input: {
      token: "abc123..."
      email: "hashed-email-from-link"
      auditData: {
        landingUrl: "https://www.example.com/marketing/confirm?uuid=abc123..."
      }
    }
  )
}

Unsubscribing via email link

Standard unsubscribe links contain the token as the uuid parameter and the hashed email as email. Hand them to the mutation as-is.

mutation UnsubscribeMarketing {
  unsubscribeMarketing(
    input: {
      token: "abc123..."
      email: "hashed-email-from-link"
      auditData: {
        landingUrl: "https://www.example.com/unsubscribe?uuid=abc123..."
      }
    }
  )
}

Unsubscribing from SMS by phone number

For SMS-only unsubscribe pages where only the phone number is known.

mutation UnsubscribeSmsMarketing {
  unsubscribeSmsMarketing(phoneNumber: "+447700900123")
}

Signing up to a specific campaign

For sites that run discrete email marketing campaigns (e.g. competition entries). marketingOptIn lets you opt the customer in to general marketing at the same time. campaignMetadata carries campaign-specific fields where supported (for example the NAME_THE_BAR campaign).

mutation SignUpForCampaign {
  signUpForEmailMarketingCampaign(
    input: {
      name: "Jane Shopper"
      email: "jane@example.com"
      campaignId: "42"
      marketingOptIn: true
      auditData: {
        messageShown: "Enter the prize draw and sign me up for offers"
        formIdentifier: "PrizeDrawCampaign42"
        formLocation: "/campaigns/prize-draw"
      }
    }
  )
}