docs
  1. Checkout Guide
  2. Configure
  3. Newsletter Subscriptions

Newsletter Subscriptions

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:

  • Middleware to check subscription status and handle the subscription webhook.
  • An HTTP endpoint that can receive subscription status requests and respond accordingly.
  • Configuration in the SCAYLE Panel to enable the subscription check and webhook handling.

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.

    Previous
    Rule Engine & Risk check
    Next up
    Checkout Translations