Newsletter Subscriptions | Developer Guides

General

Implement a custom service for newsletter subscriptions

The Checkout frontend offers the option to display a newsletter subscription checkbox for customers who have not yet signed up. You have the flexibility to integrate your own service to determine if a customer is already subscribed.If a customer already has a newsletter subscription, the checkout will seamlessly omit the checkbox. SCAYLE provides webhooks to handover the newsletter subscription information to a third-party newsletter subscription service. You can subscribe to this webhook event and connect your own systems to it. Checkout will trigger the newsletter-subscribed webhook event, once the customer activates the newsletter checkbox and navigates to the next step.

If desired, SCAYLE can activate this feature for you. Please consult your SCAYLE Account Manager for additional details.

Prerequisites

Before you start implementing this feature, make sure that you have:

Access to a third-party newsletter subscription service
Middleware configured (either by yourself or by SCAYLE)

Once you've configured these services, follow these steps:

You need to provide an HTTP service that can handle the usual load of your shop and which accepts requests from the SCAYLE networks.

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

The response of your endpoint will indicate what the status of the subscription is:

status	Description	Result
`open`	subscription does not exist	Display checkbox
`subscribed`	subscription exists	Don't display
`confirmed`	subscription was confirmed	Don't display

Status Codes

If your endpoint responds with any status code other than 200 it will be handled as if the subscription does not exist yet.

Code	Description	Response Body
`200`	subscription status in response body	see schema
`401`	authentication failed	empty
`404`	subscription not found	empty

This service needs to implement a GET endpoint according to the following schema:

Request

The URL needs to be added to the newsletter-subscribed webhook either in the SCAYLE Panel or via the ADMIN API.

Headers

Parameter	Details
X-Shop-Id	Integer The current shop-country id

Parameter

Details

X-Shop-Id

Integer

The current shop-country id

Authentication

Basic auth. The credentials for this service need to be provided to your SCAYLE Account Manager.

Query parameters

Your endpoint will be called with the following query parameters:

Parameter	Details
customerId	Integer The current customer id
emailHash	String The current customer email
customerReferenceKey	String The current customer reference key

Parameter

Details

customerId

Integer

The current customer id

emailHash

String

The current customer email

customerReferenceKey

String

The current customer reference key

Response

Your service needs to follow this specification when handling the checkout request.

Body

Response example

{
    "status": "subscribed"
}

Response schema

status string open | subscribed | confirmed

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

Go to Shops > Choose Shop Country > Storefront > Checkout Settings > Admin Webhooks.
Enter the following:
- In the Version, enter the version of the webhook. For example 1.
- In the Event Name , select newsletter-subscribed
- URL: The URL that will be called whenever the webhook is triggered.
Click SAVE.

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

Enable Subscription Checkbox on the Frontend

Once your backend service is available, you can enable the newsletter subscription checkbox on every section of the checkout:

{
    ...
    "payment": {
        "checkboxes": [
            {
                "name": "newsletterSignUp",
                "i18nKeys": { "label": "auth.newsletterSignUp" }
            }
        ]
    }
    ...
}

For more information see: Dynamic Fields Configuration.