Newsletter Subscription | Checkout

This guide explains how to integrate a custom newsletter subscription service into SCAYLE's Checkout. By following the steps, you can:

Determine if a customer is already subscribed
Handle subscription status updates

If you're using Emarsys or Mailchimp, an Add-on is available to handle this step automatically.

Prerequisites

Before you begin, you need to build the following components:

Component	Requirement	Purpose
Middleware	Mandatory	Check subscription status and handle the subscription webhook.
HTTP Endpoint	Mandatory	Receive subscription status requests and respond accordingly.
SCAYLE Panel Configuration	Mandatory	Enable the subscription check and webhook handling.

The "Subscribe to Newsletter" checkbox in checkout is not shown by default. It only appears if you configure a dynamic field for it through SCAYLE Panel.

When enabled, SCAYLE Checkout triggers a request to the subscription endpoint of your middleware. Based on the response, the checkbox will be displayed to the customer.

Integration Flow

Subscription Check

The SCAYLE Checkout sends a request to the subscription endpoint of your middleware.
Depending on the status, a "Subscribe to Newsletter" checkbox will be shown.

User Subscribes

If the user selects the checkbox and continues checkout, SCAYLE sends a newsletter-subscribed webhook to your service.

Handle Webhook

A webhook is sent to your subscription middleware to create or update the newsletter subscription.

You need to provide an HTTP service that:

Can handle the usual load of your shop.
Accepts requests from SCAYLE networks.

If you want to limit incoming traffic by IP address, your SCAYLE Account Manager can provide more information about our networks.

Endpoint Specification

Method: GET

Headers

Authorization: Basic auth (credentials need to be added to the Newsletter Subscription Configuration).
X-Shop-Id: The current shop-country ID.

Query Parameters

Parameter	Type	Description
customerId	`integer`	The current customer ID
emailHash	`string`	The current customer email hash
customerReferenceKey	`string`	The current customer reference key

Response

Status Codes:
- 200 – Subscription status in response body
- 401 – Authentication failed
- 404 – Subscription not found

Response Body Example

Status Descriptions

Status	Description	Result
open	Subscription does not exist	Display checkbox
subscribed	Subscription exists	Don’t display
confirmed	Subscription was confirmed	Don’t display

OpenAPI Specification

An example OpenAPI specification that can be customized is available for download:

Download Newsletter-Subscription-API.yaml

Configure Subscription Check Endpoint in SCAYLE

The Subscription Check Endpoint Configuration can be set via the SCAYLE Panel:

Go to Settings ➜ Imports & Jobs ➜ Imports.
Create a new Shop Import inside Checkout Configurations.
Provide the following Field as configuration_key file and upload the configuration:
1. newsletter.subscriptionCheck.password
2. newsletter.subscriptionCheck.username
3. newsletter.subscriptionCheckEndpoint.endpoint

You can create a newsletter-subscribed webhook in the SCAYLE Panel:

Go to Settings ➜ Webhooks ➜ Admin Webhooks.
Enter the following:
- Version – For example: 1
- Event Name – Select newsletter-subscribed
- URL – The URL that will be called when the webhook is triggered
Click SAVE

Alternatively, you can add a newsletter-subscribed webhook using the Admin API.

Enable Subscription Checkbox on the Frontend

Go to Settings ➜ Checkout ➜ Configurations.
Navigate to Dynamic Field ➜ Payment Options and Enable Area.
Create a new checkbox field:
- Name: newsletterSignUp
Save the configuration.

The subscription checkbox is now enabled in the checkout frontend.