# Organization API: Marketing Store API

> What a storefront calls to grow the audience: subscribe, confirm a double opt-in, the preference center and signup forms, with the store's publishable key in x-publishable-api-key.

Source: https://www.coritan.com/docs/api/reference/organizations/marketing-store-api/

What a storefront calls to grow the audience: subscribe, confirm a double opt-in, the preference center and signup forms, with the store's publishable key in `x-publishable-api-key`. Paths are under `/api/v1/orgs/{org_slug}/store/marketing`.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Organization API reference](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/store/marketing/confirm`](#op-post-api-v1-orgs-org-slug-store-marketing-confirm) | Confirm a double opt-in signup with the token from the email's link |
| GET | [`/api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}`](#op-get-api-v1-orgs-org-slug-store-marketing-forms-public-id) | The public configuration of one signup form, to draw it in a storefront |
| POST | [`/api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}/views`](#op-post-api-v1-orgs-org-slug-store-marketing-forms-public-id-views) | Count one view of the form: call it when the form is shown |
| GET | [`/api/v1/orgs/{org_slug}/store/marketing/preferences`](#op-get-api-v1-orgs-org-slug-store-marketing-preferences) | Get preferences |
| PUT | [`/api/v1/orgs/{org_slug}/store/marketing/preferences`](#op-put-api-v1-orgs-org-slug-store-marketing-preferences) | Put preferences |
| POST | [`/api/v1/orgs/{org_slug}/store/marketing/subscribe`](#op-post-api-v1-orgs-org-slug-store-marketing-subscribe) | Sign an address up to the store's marketing email |
| POST | [`/api/v1/orgs/{org_slug}/store/marketing/unsubscribe`](#op-post-api-v1-orgs-org-slug-store-marketing-unsubscribe) | Unsubscribe |

### Confirm a double opt-in signup with the token from the email's link {#op-post-api-v1-orgs-org-slug-store-marketing-confirm}

`POST /api/v1/orgs/{org_slug}/store/marketing/confirm`

Confirm a double opt-in signup with the token from the email's link. The contact joins the list (and gets the
list's welcome email, when it has one); opening the link again changes nothing. 400 ``invalid_token`` for a token that
is not valid, expired or another store's; 409 ``unsubscribed`` when the address left or was suppressed since.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The token from the confirmation email's link. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The public configuration of one signup form, to draw it in a storefront {#op-get-api-v1-orgs-org-slug-store-marketing-forms-public-id}

`GET /api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}`

The public configuration of one signup form, to draw it in a storefront. 404 for a form that is not this
store's or is archived.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `public_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Count one view of the form: call it when the form is shown {#op-post-api-v1-orgs-org-slug-store-marketing-forms-public-id-views}

`POST /api/v1/orgs/{org_slug}/store/marketing/forms/{public_id}/views`

Count one view of the form: call it when the form is shown. Answers 204.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `public_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get preferences {#op-get-api-v1-orgs-org-slug-store-marketing-preferences}

`GET /api/v1/orgs/{org_slug}/store/marketing/preferences`

What the preference center shows: ``email_masked``, the contact's ``status`` and the ``lists`` it offers, each with
``subscribed``. 400 ``invalid_token`` for a token that is not valid, expired (90 days) or another store's.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `t` | query | string | yes | The preference center token. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Put preferences {#op-put-api-v1-orgs-org-slug-store-marketing-preferences}

`PUT /api/v1/orgs/{org_slug}/store/marketing/preferences`

Save the contact's choices: they end up on exactly ``list_ids`` among the lists the preference center offers (422
``invalid`` for another), or on none and off the store's marketing email with ``unsubscribe_all``. Choosing lists
after unsubscribing is the contact's own consent and subscribes them again, unless the address bounced, was
reported as spam or was turned off by the store (409 ``marketing_blocked``). ``reason`` is kept with the
unsubscribe.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `t` | string | yes | The preference center token. |
| `list_ids` | array of integer | no | The lists to be on. |
| `unsubscribe_all` | boolean or null | no | Leave every list and stop all marketing email. |
| `reason` | string or null | no | Why, in the person's words. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Sign an address up to the store's marketing email {#op-post-api-v1-orgs-org-slug-store-marketing-subscribe}

`POST /api/v1/orgs/{org_slug}/store/marketing/subscribe`

Sign an address up to the store's marketing email. Always ``{"ok": true, "confirmation_required"}`` for a valid
address, so a form never learns whether the store knew it. ``consent`` must be true. A list that needs a
confirmation click emails the address a link; an address that unsubscribed, bounced or complained stays out.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes |  |
| `first_name` | string or null | no |  |
| `last_name` | string or null | no |  |
| `fields` | object or null | no | Custom field values by key. |
| `list_ids` | array of integer or null | no | The lists to join. |
| `list` | string or null | no | One list, by id or by name. |
| `tags` | array of string or null | no |  |
| `consent` | any or null | no | Must be the boolean true: the person agreed to receive marketing email. |
| `consent_text` | string or null | no | The words the person agreed to. |
| `source` | string or null | no | Where on the storefront, such as footer. |
| `form_id` | string or null | no | A signup form's public id or id. |
| `turnstile_token` | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Unsubscribe {#op-post-api-v1-orgs-org-slug-store-marketing-unsubscribe}

`POST /api/v1/orgs/{org_slug}/store/marketing/unsubscribe`

Unsubscribe the contact a marketing email was sent to, from every list, with the token of that email's link. The
address goes on the store's suppression list. Answers ``{"ok": true}`` as often as it is posted; 400
``invalid_token`` for a token that is not valid or is another store's.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `t` | string | yes | The token from a marketing email's unsubscribe link. |
| `reason` | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |