Create Newsletter
About
The createNewsletter mutation subscribes an email address to the store newsletter on the current channel. Use this mutation to:
- Add newsletter opt-in to the storefront footer or account page
- Re-subscribe a customer who previously unsubscribed
- Capture marketing consent during registration or checkout
- Track submissions using
clientMutationId
The subscription is scoped to the current channel.
Authentication
The mutation is public — the storefront key alone is enough, so a footer signup form works for guests.
A customer token is optional. When one is sent, the subscription is linked to that customer's account; without it the row is stored as a guest subscription.
Authorization: Bearer <accessToken>Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
input | createNewsletterInput! | ✅ Yes | Input object containing the subscription fields. |
Input Fields (createNewsletterInput)
| Field | Type | Required | Description |
|---|---|---|---|
customerEmail | String! | ✅ Yes | Email address to subscribe. Must be valid and unique in the subscribers list. |
clientMutationId | String | ❌ No | Optional client-side identifier for tracking the mutation request. |
Possible Returns
| Field | Type | Description |
|---|---|---|
newsletter.success | Boolean! | true if the subscription was created successfully. |
newsletter.message | String! | Human-readable confirmation or error message. |
clientMutationId | String | Echoed back from the input if provided. |
Use Cases
1. Storefront Footer Opt-in
Trigger this mutation when a logged-in customer submits the newsletter form, then display message as feedback.
2. Account Preferences
Let customers manage their marketing consent from the account settings page.
Best Practices
- Validate email client-side first to reduce unnecessary API calls.
- Always read
successbefore showing a success state. - Handle the already-subscribed case gracefully — surface the server
message.