# Organization API: Organizations & Members: Conversions

> The 6 Organization API operations for conversions.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/conversions/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/conversions`](#op-get-api-v1-orgs-org-slug-conversions) | List the ad platforms purchases are sent to, and how each is doing |
| GET | [`/api/v1/orgs/{org_slug}/conversions/deliveries`](#op-get-api-v1-orgs-org-slug-conversions-deliveries) | Read what each platform was sent, and why anything was not |
| GET | [`/api/v1/orgs/{org_slug}/conversions/microsoft/feed`](#op-get-api-v1-orgs-org-slug-conversions-microsoft-feed) | Fetch the offline conversions file Microsoft Advertising imports |
| PUT | [`/api/v1/orgs/{org_slug}/conversions/{kind}`](#op-put-api-v1-orgs-org-slug-conversions-kind) | Turn an ad platform on or off and change its settings |
| POST | [`/api/v1/orgs/{org_slug}/conversions/{kind}/rotate-feed-token`](#op-post-api-v1-orgs-org-slug-conversions-kind-rotate-feed-token) | Replace the token in the Microsoft Ads file address |
| POST | [`/api/v1/orgs/{org_slug}/conversions/{kind}/test`](#op-post-api-v1-orgs-org-slug-conversions-kind-test) | Send a made-up purchase to an ad platform in test mode |

### List the ad platforms purchases are sent to, and how each is doing {#op-get-api-v1-orgs-org-slug-conversions}

`GET /api/v1/orgs/{org_slug}/conversions`

Every ad platform the organization can send purchases to, with its settings and how it is doing.

Needs the Admin or Owner role. There is one entry for each of ``ga4``, ``google_ads``, ``meta_capi``,
``tiktok_events``, ``microsoft_ads``, ``reddit_ads`` and ``x_ads``, whether or not it was ever set up.
An entry has ``enabled``, ``test_mode``, ``config`` (the settings that are not secret), ``secret_set``
(whether a secret is saved; the secret is never answered), ``fields`` and ``secret`` (what a form for
the kind asks), ``last_delivery`` (the newest event the kind was sent, with its status) and
``coverage``: ``orders`` is how many first purchases were paid in the last 30 days, ``sent`` how many
of them the kind was sent, and ``rate`` is ``sent`` over ``orders`` (null with no orders).
Microsoft Ads has no secret. Its entry has ``feed_url_masked``, the address of its file with the token
hidden, and when Microsoft Advertising last fetched it.

#### Parameters

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

#### Responses

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

### Read what each platform was sent, and why anything was not {#op-get-api-v1-orgs-org-slug-conversions-deliveries}

`GET /api/v1/orgs/{org_slug}/conversions/deliveries`

What each platform was sent, newest first, and why anything was not.

Needs the Admin or Owner role. Every row is one event for one platform: ``event`` is ``purchase``
(a first purchase), ``renewal``, ``upgrade``, ``free_server``, ``sign_up``, ``refund`` or
``chargeback``; ``status`` is ``sent``, ``skipped`` (``error`` says why: the buyer did not allow
marketing, the platform has no such event, renewals are off) or ``failed`` (``http_status`` and
``error`` hold the platform's answer, and a timeout or a server error is tried again, three
attempts in all). ``invoice`` names the invoice the row belongs to. Filter by ``kind``, ``status``
and ``invoice_number``; ``count`` is the total that match.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `kind` | query | string or null | no | ga4, google_ads, meta_capi, tiktok_events, microsoft_ads, reddit_ads or x_ads. |
| `status` | query | string or null | no | sent, failed or skipped. |
| `invoice_number` | query | string or null | no | Only the deliveries of this invoice, its refunds and its chargebacks. |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

### Fetch the offline conversions file Microsoft Advertising imports {#op-get-api-v1-orgs-org-slug-conversions-microsoft-feed}

`GET /api/v1/orgs/{org_slug}/conversions/microsoft/feed`

The organization's purchases as the CSV file Microsoft Advertising imports as offline conversions.

Microsoft Advertising fetches this address itself. Copy the whole address from the Microsoft Ads
integration, which answers it once (when the integration is first turned on and when it is replaced),
into a schedule under Conversions, Offline conversions, Schedules. It needs no sign-in: the ``token`` in
the address is the credential.

The file lists paid invoices that were a first purchase or an upgrade (and a renewal when renewals are
on), paid in the last ``lookback_days`` (30 unless set), paid at least ``browser_grace_minutes`` ago (120
unless set) and paid after the integration was turned on. Only a buyer who allowed marketing is listed.
It leaves out refunded invoices, free servers and every invoice the thank-you page reported with the UET
tag (``POST .../storefront/conversions/microsoft/claim``). A listed invoice stays listed on later fetches
within the lookback, and Microsoft Advertising drops the repeats.

The first line is ``Parameters:TimeZone=+0000``, then the header ``Microsoft Click Id``, ``Conversion
Name``, ``Conversion Time``, ``Conversion Value``, ``Conversion Currency`` and ``Hashed Email Address``,
then a row per invoice, oldest first. Every cell is in double quotes and every line ends in CRLF. A row
holds the buyer's ``msclkid`` (32 hex digits or a GUID), the integration's ``conversion_name``, the time
the invoice was paid in UTC as ``MM/DD/YYYY HH:MM:SS``, the total with two decimals, the currency code
and the SHA-256 of the buyer's email address (lower case, dots taken out of the part before the ``@``
and anything from a ``+``). A buyer without a click ID is listed by the email hash alone when
``email_only_rows`` is on (the default) and the visit came from Microsoft. In test mode the file has the
header and no rows.

At most 30 requests an hour from one IP address for one organization's file (429).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `token` | query | string or null | no | The file token, as it is in the address Microsoft Ads integration answered. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | The CSV file. |
| `404` | The token is wrong or missing, the organization is unknown, or its Microsoft Ads integration is off. |
| `429` | More than 30 requests in an hour from one IP address for this file. |
| `422` | The request is not valid. `detail` lists each problem. |

### Turn an ad platform on or off and change its settings {#op-put-api-v1-orgs-org-slug-conversions-kind}

`PUT /api/v1/orgs/{org_slug}/conversions/{kind}`

Turn a platform on or off, set its test mode, change its settings, set or clear its secret.

Needs the Admin or Owner role. Send only what changes. ``config`` keys replace the saved ones and a
null or empty string removes one; ``labels`` (Google Ads) and ``events`` (X) replace the whole map.
``secret`` is write only: it is sealed, never answered and never written to the audit log, and an
empty string clears it. X takes an object of ``consumer_key``, ``consumer_secret``, ``access_token``
and ``access_token_secret``. Google Ads and Microsoft Ads take no secret, and a secret for them
answers 422. A value that does not fit, or a platform turned on without what it needs, answers 422
with ``detail``, the sentence to show, and ``field``, the input it belongs to. Every ID is checked
as the analytics and ad tags check theirs.

Turning Microsoft Ads on the first time makes the address of its file, and only that answer carries
the whole address in ``feed_url``. Copy it into a schedule in Microsoft Advertising. Later answers
show it with the token hidden. The answer is ``{integration, changed, feed_url}``. Each change is
recorded in the audit log without any secret.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | path | string | yes | ga4, google_ads, meta_capi, tiktok_events, microsoft_ads, reddit_ads or x_ads. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no | Turn the integration on or off. It needs its settings and secret first (422 names the first one missing). |
| `test_mode` | boolean or null | no | Send every event as a test: Meta and TikTok with the test event code, Google Analytics to its validation endpoint, Reddit with its test flag. Google Ads and X have no test mode. |
| `config` | object or null | no | Settings to change. A key replaces the stored one and null removes it. labels and events replace the whole map. |
| `secret` | string or object or null | no | The platform's secret. Write only: it is sealed and never answered, only secret_set. An empty string clears it. X takes an object of its four OAuth values. |

#### Responses

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

### Replace the token in the Microsoft Ads file address {#op-post-api-v1-orgs-org-slug-conversions-kind-rotate-feed-token}

`POST /api/v1/orgs/{org_slug}/conversions/{kind}/rotate-feed-token`

Replace the token in the Microsoft Ads file address, so the old address stops working.

Needs the Admin or Owner role. The answer is ``{integration, feed_url}`` and the only one that shows
the new address whole. Put it in the schedule in Microsoft Advertising; from now on the old address
answers 404. Purchases the file already listed stay listed. Answers 409 before Microsoft Ads was
first turned on, since that makes the first address.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | path | string | yes | microsoft_ads, the one platform that fetches a file from Coritan. |
| `org_slug` | path | string | yes |  |

#### Responses

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

### Send a made-up purchase to an ad platform in test mode {#op-post-api-v1-orgs-org-slug-conversions-kind-test}

`POST /api/v1/orgs/{org_slug}/conversions/{kind}/test`

Send one made-up purchase to a platform in test mode and answer what the platform said.

Needs the Admin or Owner role. The event is for one currency unit of a product called "Test
product" and carries nothing about a person. Meta and TikTok send their test event code, Google
Analytics its validation endpoint and Reddit its test flag, so nothing reaches live reporting. The
platform needs its settings and secret saved first (422 names the missing one). Google Ads and X have
no test mode, so a test would count as a real sale and answers 422, and Microsoft Ads fetches its
file and takes no events. At most ten test events an hour for each platform (429). The test is not
logged as a delivery and is not counted in coverage. The answer is ``{kind, event, status, ok,
http_status, error, event_id}``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | path | string | yes | ga4, google_ads, meta_capi, tiktok_events, microsoft_ads, reddit_ads or x_ads. |
| `org_slug` | path | string | yes |  |

#### Responses

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