Marketing Consent

How marketing consent is captured and passed for orders via Violet.

This page describes how marketing consent is captured during checkout when using Violet when using Direct Order Submission.

What is Marketing Consent?

Marketing consent is the explicit permission a shopper gives to receive marketing communications, such as promotional email messages, from a merchant. Collecting and honoring this consent is important for privacy compliance and customer trust.

Note: The communication_preferences object is applied at the bag level within each order. This means that different bags (from different merchants) within the same order can have different communication preferences, allowing for merchant-specific consent handling.

Platform Scope

• Supported: Shopify only

Overview

The create_order endpoint supports a communication_preferences field, allowing you to specify customer communication preferences at the time of order creation. This enables more granular control over how and when customers receive notifications (such as order confirmation, fulfillment, and marketing emails) from merchants.

This document describes:

• The endpoint and request structure (in snake_case)

• The new communication_preferences object

• Platform-specific handling for Shopify

• Default behavior when preferences are not specified

• Example requests and responses

• A summary table of preference mapping

Endpoint

POST /api/orders

• Creates a new order in Violet.

• Accepts a JSON request body with order details, including the new communication_preferences field.

Request Body: Communication Preferences

Field: communication_preferences

• Type: Object (optional)

• Purpose: Specifies the customer's preferences for receiving communications related to the order.

Structure

{
  "order": {
    "bags": [
      {
        "skus": [...],
        "communication_preferences": {
          "email_preferences": {
            "order_confirmation": "OPT_IN" | "NO_OPT_IN",
            "order_fulfillment": "OPT_IN" | "NO_OPT_IN", 
            "marketing": "OPT_IN" | "NO_OPT_IN"
          }
        }
      }
    ]
  }
}

• email_preferences: Object containing preferences for different types of email communications.

  • order_confirmation: Preference for order confirmation emails.

  • order_fulfillment: Preference for fulfillment/shipping emails.

  • marketing: Preference for marketing/promotional emails.

Enum values:

• OPT_IN: Customer explicitly opts in to receive this type of communication.

• NO_OPT_IN: Customer does not opt in.

Default Behavior

When the communication_preferences field is not included in the request, the following defaults apply:

Shopify Defaults

• marketing: NO_OPT_IN

• order_confirmation: OPT_IN

• order_fulfillment: OPT_IN

Example Request

{
  "order": {
    "app_order_id": "mario-test-1",
    "customer": {...},
    "bags": [
      {
        "skus": [...],
        "communication_preferences": {
          "email_preferences": {
            "order_confirmation": "OPT_IN",
            "order_fulfillment": "OPT_IN",
            "marketing": "NO_OPT_IN"
          }
        }
      }
    ]
  }
}

Platform-Specific Handling

Shopify

• order_confirmation and order_fulfillment:

  • If you send "OPT_IN", Violet will map this to "SINGLE_OPT_IN" in the response and on Shopify (meaning the customer is opted in for this order only).

  • If you send "NO_OPT_IN", it will remain "NO_OPT_IN".

  • Default when not specified: OPT_IN (mapped to SINGLE_OPT_IN)

• marketing:

  • "OPT_IN" and "NO_OPT_IN" are mapped directly.

  • Default when not specified: NO_OPT_IN

API Response

On success, the API will return the created order object, including the resolved communication_preferences as stored in Violet.

Example Success Response:

{
  "bags": [
    {
      "id": 64579,
      "communication_preferences": {
        "email_preferences": {
          "order_confirmation": {
            "requested": "OPT_IN",
            "result": "SINGLE_OPT_IN"
          },
          "order_fulfillment": {
            "requested": "OPT_IN", 
            "result": "SINGLE_OPT_IN"
          },
          "marketing": {
            "requested": "NO_OPT_IN",
            "result": "NO_OPT_IN"
          }
        }
      }
    }
  ]
}

Error Responses:

• If the communication_preferences object is malformed or contains invalid values, you will receive a 400 Bad Request with details.

• If the platform does not support a given preference, the API will either ignore the unsupported value or map it to the closest supported value, and this will be reflected in the response.

Summary Table

Platform	Field	Default	Supported Values	Notes
Shopify	marketing	NO_OPT_IN	OPT_IN, NO_OPT_IN	Direct mapping
Shopify	order_confirmation	OPT_IN → SINGLE_OPT_IN	OPT_IN → SINGLE_OPT_IN, NO_OPT_IN	OPT_IN automatically mapped to SINGLE_OPT_IN
Shopify	order_fulfillment	OPT_IN → SINGLE_OPT_IN	OPT_IN → SINGLE_OPT_IN, NO_OPT_IN	OPT_IN automatically mapped to SINGLE_OPT_IN