docs

Newsletter Subscription (hidden)

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:

ComponentRequirementPurpose
MiddlewareMandatoryCheck subscription status and handle the subscription webhook.
HTTP EndpointMandatoryReceive subscription status requests and respond accordingly.
SCAYLE Panel ConfigurationMandatoryEnable 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

1
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.
    • 2
    User Subscribes
    If the user selects the checkbox and continues checkout, SCAYLE sends a newsletter-subscribed webhook to your service.
    3
    Handle Webhook
    A webhook is sent to your subscription middleware to create or update the newsletter subscription.

    Build Newsletter Subscription Check Endpoint

    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

    ParameterTypeDescription
    customerIdintegerThe current customer ID
    emailHashstringThe current customer email hash
    customerReferenceKeystringThe 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

    StatusDescriptionResult
    openSubscription does not existDisplay checkbox
    subscribedSubscription existsDon’t display
    confirmedSubscription was confirmedDon’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:

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

    Create a Newsletter-Subscribed Webhook

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

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

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

    Enable Subscription Checkbox on the Frontend

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

    The subscription checkbox is now enabled in the checkout frontend.