# Subscribe a customer from the browser

> POST /api/v0/subscribe/request with your access token sends a sign-up from your site. Depending on your shop setting it subscribes right away (200) or waits for an email confirmation (202). Fields, curl, Releva.requestSubscribe, errors and limits.

`POST https://releva.ai/api/v0/subscribe/request` sends a sign-up from your storefront. It uses the access token, which is safe to expose in a browser or an app. What it does depends on **Subscription Request Behavaior** in **Settings › Messaging**: it either subscribes the customer right away, or records a request that the customer confirms by email (double opt-in).

## When to use it

* **You use the Releva JavaScript SDK:** call `Releva.requestSubscribe(...)`. It calls this endpoint for you (see [The JavaScript SDK](https://releva.ai/documentation/reference/consent/subscribe-from-the-browser/#the-javascript-sdk)).
* **You build your own sign-up form and post from the browser without the SDK:** call this endpoint.
* **You subscribe customers from your server:** use [Subscribe a customer from your server](https://releva.ai/documentation/reference/consent/subscribe-a-customer/) instead. It always subscribes right away.

**Never send your secret key from a browser.** This endpoint takes the access token only.

## The two behaviours

**Subscription Request Behavaior** (the label is spelled this way in the admin) is shown in **Settings › Messaging** when **Subscription Management** is **Internal**.

| Setting                   | What a request does                                                                                                                                                                                                                                                                                                                                       | Success response                 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| **Subscribe right away**  | Subscribes the customer like the server-side call, and tags the `subscribe` event with `request`. If the email address or phone number already belongs to a profile, that profile is used, and the `userId` you sent is merged into it.                                                                                                                   | `200` with `{ "userId": "..." }` |
| **Wait for confirmation** | Does not subscribe. Stores the email address, phone number, birthday and tags on the profile (an `unsubscribeLink` is kept only if the profile is already subscribed), and records a `subscribeRequest` event with the requested subscriptions and the locale. The customer is subscribed when they open the `{{subscribeLink}}` in a confirmation email. | `202` with `{}`                  |

Your access token is public, so with **Subscribe right away** anyone who copies it can subscribe any address. **Wait for confirmation** prevents that. To set it up end to end, read [Set up double opt-in](https://releva.ai/documentation/reference/consent/set-up-double-opt-in/).

If you use **Subscribe right away**, limit the damage of a wrong sign-up: create a triggered campaign on `subscribe` events with the tag `request`, and send an email that welcomes the user and offers a link to unsubscribe in case they were subscribed in error.

If you are unsure which behaviour is right for you, email <support@releva.ai>.

With **Subscribe right away**, call this endpoint with the new set of subscriptions when a user updates their preferences. With **Wait for confirmation**, the call only records a request: `subscriptions`, `addSubscriptions` and `removeSubscriptions` do not change the profile until the customer confirms.

## Authentication

Send your shop’s **access token** as a bearer token:

```plaintext
authorization: Bearer $RELEVA_ACCESS_TOKEN
```

Find it under **Settings › Shop & Integration**; see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

Authentication failures answer `400`, not `401`:

| Problem                                                                | Message                                                                                                              |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| No `authorization` header                                              | `Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required.` |
| The header is not `Bearer` followed by a token                         | ``Authorization header is malformed. It should look like `Bearer <string>`.``                                        |
| The token is not a UUID                                                | `The access token you provided is invalid.`                                                                          |
| No shop has this access token (also when you send the secret key here) | `Domain with the provided access token cannot be found.`                                                             |

A shop that is switched off answers `402` with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

## Request

`POST /api/v0/subscribe/request` with `content-type: application/json`. Send at least one of `email`, `phoneNumber` or `userId`.

| Field                     | Type             | Notes                                                                                                                                                                                                                                                                                     |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                   | string           | The customer’s email address.                                                                                                                                                                                                                                                             |
| `phoneNumber`             | string           | International format with a leading `+` and digits only, for example `+15555550199`. A number without `+` gets your shop country’s dialling code added before it is checked.                                                                                                              |
| `userId`                  | string           | The visitor’s Releva id (the `rlv_u` cookie). The SDK sends it for you.                                                                                                                                                                                                                   |
| `firstName`               | string           | The customer’s first name.                                                                                                                                                                                                                                                                |
| `lastName`                | string           | The customer’s last name.                                                                                                                                                                                                                                                                 |
| `birthday`                | string           | Date only, exactly `YYYY-MM-DD`.                                                                                                                                                                                                                                                          |
| `subscriptions`           | array of strings | Subscription keys, stored exactly as sent. With **Wait for confirmation** they are applied when the customer confirms. Without them, your user-visible subscriptions apply (see [Subscribe a customer from your server](https://releva.ai/documentation/reference/consent/subscribe-a-customer/#request)). |
| `addSubscriptions`        | boolean          | `true` adds `subscriptions` to the profile’s list instead of replacing it. With **Wait for confirmation**, the confirmation always adds.                                                                                                                                                  |
| `removeSubscriptions`     | array of strings | Keys to remove from the profile’s list (**Subscribe right away** only).                                                                                                                                                                                                                   |
| `tags`                    | array of strings | Added to the profile’s tags, for example the form the sign-up came from.                                                                                                                                                                                                                  |
| `unsubscribeLink`         | string           | An absolute URL: this customer’s own unsubscribe page in your shop. Used only when **Subscription Management** is **External**; there it takes precedence over your shop’s **Email Unsubscribe URL**. Kept only while the profile is subscribed.                                          |
| `rejectAlreadySubscribed` | boolean          | `true` answers `409` and does nothing when this email address has ever been subscribed or unsubscribed in your shop. Checks `email` only. Rejected requests count toward a rate limit (see [Limits](https://releva.ai/documentation/reference/consent/subscribe-from-the-browser/#limits)).                                                                            |
| `attributions`            | object           | Links the change to a message: `emailId`, `campaignId`, `textMessageId`, `viberMessageId`, `whatsappMessageId`, all strings.                                                                                                                                                              |
| `locale`                  | string           | A two-letter ISO 639-1 code such as `en`. With **Wait for confirmation** it is recorded on the `subscribeRequest` event; without it, your shop’s locale is recorded.                                                                                                                      |

Fields not in this table are ignored.

```plaintext
curl -X POST 'https://releva.ai/api/v0/subscribe/request' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "email": "maria@example.com",
    "subscriptions": ["weeklyNewsletter"],
    "addSubscriptions": true,
    "tags": ["footer-form"],
    "locale": "en"
  }'
```

## Response

| Status | Body                              | Meaning                                                                                                                                                                                                                                   |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | `{ "userId": "DEMO-1001" }`       | **Subscribe right away**: the customer is subscribed. If you track visitors yourself, store this id as the visitor’s id: it can differ from the `userId` you sent when the email address or phone number belonged to an existing profile. |
| `202`  | `{}`                              | **Wait for confirmation**: the request is recorded. The customer is not subscribed until they open the confirmation link.                                                                                                                 |
| `409`  | `{ "code": "alreadySubscribed" }` | `rejectAlreadySubscribed` was `true` and the email address has a consent history. Nothing was written.                                                                                                                                    |

## The JavaScript SDK

`Releva.requestSubscribe` posts to this endpoint with the access token and the visitor’s `rlv_u` id. Call `Releva.push()` on the page first: the access token and the locale come from the last push.

```plaintext
Releva.requestSubscribe(
  'maria@example.com',   // email
  'Maria',               // firstName
  'Example',             // lastName
  null,                  // phoneNumber
  {},                    // custom (ignored by this endpoint)
  ['weeklyNewsletter'],  // subscriptions
  function (response) { /* any 2xx: 200 or 202 */ },
  function (error) { /* error.status and error.body, for example 409 */ },
  false,                 // addSubscriptions
  null,                  // birthday
  null,                  // attributions
  ['footer-form'],       // tags
  { rejectAlreadySubscribed: true } // options
);
```

The SDK leaves out an empty `subscriptions` array, so a form without subscription choices never clears a returning customer’s list. When the response carries a `userId`, the SDK stores it in the `rlv_u` cookie. The full signature is in the [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/).

## Errors

Errors have the shape `{ "message": "..." }`, except the `409`.

| Status | When                                                                              | Body or message                                                                                                                                                                      |
| ------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed                                                             | See [Authentication](https://releva.ai/documentation/reference/consent/subscribe-from-the-browser/#authentication)                                                                                                                                                |
| `400`  | None of `email`, `phoneNumber` or `userId`                                        | `At least one of (email, phoneNumber, userId) is required.`                                                                                                                          |
| `400`  | A field has the wrong type or format                                              | The same messages as [Subscribe a customer from your server](https://releva.ai/documentation/reference/consent/subscribe-a-customer/#errors), for example `The 'email' field must be a valid e-mail.` |
| `402`  | The shop is switched off                                                          | See [Authentication](https://releva.ai/documentation/reference/consent/subscribe-from-the-browser/#authentication)                                                                                                                                                |
| `409`  | `rejectAlreadySubscribed: true` and the email address has a consent history       | `{ "code": "alreadySubscribed" }`                                                                                                                                                    |
| `413`  | The body is larger than 800 KB                                                    | `request entity too large`                                                                                                                                                           |
| `429`  | Too many failed requests with `rejectAlreadySubscribed: true` from one IP address |                                                                                                                                                                                      |

## Limits

* HTTPS only. Body size: 800 KB.
* Rate limit: 30 requests per 15 minutes per IP address, counting only requests that send `rejectAlreadySubscribed: true` and get an error answer (such as the `409`). Other requests are not limited. Responses carry the standard `RateLimit` and `RateLimit-Policy` headers.
* One customer per request.

## Next steps

* [Set up double opt-in](https://releva.ai/documentation/reference/consent/set-up-double-opt-in/): Make sign-ups wait for an email confirmation, so a copied access token cannot subscribe strangers.
* [Check an email’s consent history](https://releva.ai/documentation/reference/consent/check-consent-history/): Find out before you show a new-subscriber offer whether an address has subscribed before.
* [Choose a consent call](https://releva.ai/documentation/reference/consent/choose-a-consent-call/): Compare this call with the server-side subscribe and the profile button.