# Marketing Consent

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

```json
{
  "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

```json
{
  "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:**

```json
{
  "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` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/prism/checkout-guides/guides/marketing-consent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.