> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subtotal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad-Sharing Opt-Outs

> Record a consumer's request not to have their purchases shared with ad platforms.

## Overview

`POST /ad-sharing/opt-outs` records a consumer's request not to have their purchases shared with ad
platforms. The endpoint only records opt-outs; it cannot grant permission.

An opt-out takes effect after the API successfully records it and applies to sharing from that point
forward. It does not retract or delete data already delivered to ad platforms. Submit opt-outs
promptly after receiving a consumer request to meet applicable deadlines and because sharing can
continue until the API returns `204`.

<Warning>
  Recording an opt-out cannot be undone through the API. Treat each call as permanent.
</Warning>

## Recording an opt-out

Identify the consumer by email or by a connection you own. Requests use the same
[API key authentication](/docs/subtotal-api) as the rest of the Subtotal API.

Submitting an email address directly:

```bash theme={null}
curl -X POST https://api.subtotal.com/ad-sharing/opt-outs \
  -H "X-Api-Key: {yourkeyvalue}" \
  -H "Content-Type: application/json" \
  -d '{"email": "shopper@example.com"}'
```

Or naming a connection, when you have its ID and would rather not look up the address:

```bash theme={null}
curl -X POST https://api.subtotal.com/ad-sharing/opt-outs \
  -H "X-Api-Key: {yourkeyvalue}" \
  -H "Content-Type: application/json" \
  -d '{"connection_id": "01HZY7QK8N4M2P6R3T9V5W1X0Y"}'
```

A successful call returns **`204 No Content`** with an empty body.

### Request fields

| Field           | Type   | Description                                                                                            |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `email`         | string | The consumer's email address. Required unless `connection_id` is supplied. Maximum 254 characters.     |
| `connection_id` | string | An owned, non-simulated connection with a usable email. When supplied, the connection's email is used. |

Supply at least one. If you supply both, `connection_id` wins and `email` is ignored.

### Responses

| Status | Meaning                                                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| `204`  | The request was accepted.                                                                                        |
| `401`  | The API key is missing or invalid.                                                                               |
| `404`  | The `connection_id` does not exist, does not belong to you, or is a simulated connection.                        |
| `422`  | Neither field was supplied, the selected connection has no usable email, or a field exceeded its maximum length. |

Email matching ignores case and surrounding whitespace, so `Shopper@Example.com` and
`shopper@example.com` are treated as the same address.