---
uuid: 3ba2d165-e378-4796-803b-e4797861a6be
date_created: 2026-02-26T16:41:35.477Z
date_updated: 2026-04-03T17:59:09.215Z
seo_url: subscribe-a-customer-to-a-newsletter-and-manage-the-subscription
category: Customer account
tags: 
  - Subscriptions
  - Newsletters
  - Customers
routes: 
  - POST /v1/subscriptions
  - GET /v0/subscriptions/{subscription_id}
  - PATCH /v1/subscriptions/{subscription_id}
---

# Subscribe a customer to a newsletter and manage the subscription

This scenario describes the journey for subscribing a customer to one or more Club Med newsletters. It covers the initial subscription creation, retrieving the current state through the identifier returned by the API, and updating the subscription to add another newsletter or trigger an unsubscribe operation.

The entry point is `POST /v1/subscriptions`, which returns a subscription `id` and a `customer_id`. This identifier is then used by `GET /v0/subscriptions/{subscription_id}` to read the current subscription state, and by `PATCH /v1/subscriptions/{subscription_id}` to execute either a `subscribe` or an `unsubscribe` operation.

## Flow

```mermaid
flowchart LR
    step0["Create the newsletter subscription"]
    step1["Review the subscription state"]
    step2["Update the newsletter subscription"]
    step0 --> step1
    step1 --> step2
```

## Overview

This journey lets you manage a customer newsletter subscription using a technical subscription identifier.

The subscription is created with `POST /v1/subscriptions`. Its state is read with `GET /v0/subscriptions/{subscription_id}`. It is updated with `PATCH /v1/subscriptions/{subscription_id}`.

The most credible functional sequence is the following:

```mermaid
flowchart TD
  A["Prepare customer data and target newsletters"] --> B["POST /v1/subscriptions"]
  B --> C["Retrieve subscription_id"]
  C --> D["GET /v0/subscriptions/{subscription_id}"]
  D --> E["PATCH /v1/subscriptions/{subscription_id}"]
  E --> F["Read the state again if needed"]
```

## Prerequisites

* Have the `x-api-key` header
* Provide the `accept-language` header with a valid locale, for example `fr-FR`
* For read and update operations, have a `subscription_id` obtained from the `POST` call
* For an additional subscribe operation through `PATCH`, know a valid `newsletter_subscriptions` value
* The full request body schema for `POST /v1/subscriptions` is not verifiable with the available sources
* The description of `POST /v1/subscriptions` indicates that personal information is expected, that the target newsletters must be specified, that the contact channel must be provided, and that either `Gender` or `Civility` is mandatory

\:::warning Important
`POST /v1/subscriptions` can fail if opt-ins and provided fields are inconsistent, if a subscription already exists for the customer, or if `optin` is not set to `true`.
\:::

\:::info Preparing newsletter IDs
The `GET /v0/newsletters` route exists and lets you retrieve the list of subscribable newsletters, for example `CLUBMED`. It is useful before starting the main journey.
\:::

## 1 - Create the newsletter subscription

This route creates a newsletter subscription from the customer's personal information.

#### Prerequisites

Send the contact details, the target newsletters, and a contact channel. According to the Swagger contract, the body must also include either `Gender` or `Civility`.

#### Calling CURL

```bash
curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "country": "FR", "newsletter_subscriptions": ["CLUBMED"], "channel": "EMAIL", "gender": "FEMALE", "optin": true}' \
  "https://api.clubmed.com/v1/subscriptions"
```

#### Example answer

```json
{
  "id": "subscription-1",
  "customer_id": "123456789"
}
```

> **info:** Keep the returned subscription identifier: it is required to review or update the consent later on.

***

**Response codes**

* `200 OK` or `201 Created`: the subscription is created.
* `400 Bad Request`: inconsistent data, existing subscription, or invalid JSON.
* `403 Forbidden`: the country or channel is not allowed.

**Related route**: [POST https://api.clubmed.com//v1/subscriptions](https://api.clubmed.com/doc?search=POST%20%2Fv1%2Fsubscriptions)

## 2 - Review the subscription state

This route returns the current state of a newsletter subscription.

#### Prerequisites

Use the subscription identifier returned at creation time.

#### Calling CURL

```bash
curl -X GET \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  "https://api.clubmed.com/v0/subscriptions/{subscription_id}"
```

#### Example answer

```json
{
  "id": "subscription-1",
  "customer_id": "123456789",
  "email": "jane@example.com",
  "phone": "+33600000000",
  "origin_code": "CUSTOMER_ACCOUNT",
  "newsletter_subscriptions": [
    "CLUBMED"
  ],
  "optins": {
    "email": true,
    "sms": false
  }
}
```

> **info:** You can review opt-ins, active newsletters, and the subscription origin before updating anything.

***

**Response codes**

* `200 OK`: the subscription is returned.
* `400 Bad Request`: invalid parameters.
* `403 Forbidden`: access denied.
* `404 Not Found`: subscription not found.

**Related route**: [GET https://api.clubmed.com//v0/subscriptions/{subscription\_id}](https://api.clubmed.com/doc?search=GET%20%2Fv0%2Fsubscriptions%2F%7Bsubscription_id%7D)

## 3 - Update the newsletter subscription

This route updates the newsletter subscription state, for example to unsubscribe or resubscribe.

#### Prerequisites

Use the subscription identifier and the expected operation in the body, such as `unsubscribe` or `subscribe`.

#### Calling CURL

```bash
curl -X PATCH \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"operation": "subscribe", "parameters": {"newsletter_subscriptions": ["CLUBMED"], "origin_code": "CUSTOMER_ACCOUNT"}}' \
  "https://api.clubmed.com/v1/subscriptions/{subscription_id}"
```

#### Example answer

```http
HTTP/1.1 204 No Content
```

> **info:** Success is returned without a response body. If needed, call the read step again right after the update.

***

**Response codes**

* `204 No Content`: the subscription is updated.
* `400 Bad Request`: invalid operation or malformed JSON.
* `403 Forbidden`: access denied.
* `404 Not Found`: subscription not found.

**Related route**: [PATCH https://api.clubmed.com//v1/subscriptions/{subscription\_id}](https://api.clubmed.com/doc?search=PATCH%20%2Fv1%2Fsubscriptions%2F%7Bsubscription_id%7D)