Organization API: Organizations & Members: Conversions

Part of Organizations & Members.

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.

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.

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).

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.

application/json (required)

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.

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}.