Change a conversion goalMenu

Change a conversion goal

PATCH/v1/conversion-goals/{id}

Requires an API key with the conversion-goals:write scope. About keys and scopes

Works with integration, agent and partner keys.

Safe to retry: a repeat sets the same values again. About idempotency

Changes the attribution window, value property or currency for events processed from now on; conversions already counted keep their attribution and value, and are not counted again under the new window. Changing the window sets windowChangedAt, so a reader can tell the all-time totals mix both. Clearing valueProperty clears currency too. The event and its filter cannot change: create another goal.

Path parameters

idstringrequired

The conversion goal's id.

uuid

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Request body

attributionWindowDurationInputoptional

How long after a message the event still counts: 1 to 3,650 whole days.

2 child attributes

valueintegerrequired: min > 0
unitstringrequired: one of seconds, minutes, hours, days

valuePropertystring | nulloptional

1–64 characters

currencystring | nulloptional

pattern ^[A-Z]{3}$

Returns

Returns 200 OK with a ConversionGoal in data. It can also return 409 Conflict, 413 Payload Too Large or 415 Unsupported Media Type; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

200 OKThe goal as changed.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.
413 Payload Too LargeThe body is larger than this operation accepts (PAYLOAD_TOO_LARGE).
415 Unsupported Media TypeThe body is not JSON, or not the upload the operation takes (UNSUPPORTED_MEDIA_TYPE).

idstringrequired

uuid

campaignIdstring | nullrequired

The campaign it measures.

uuid

journeyIdstring | nullrequired

The journey it measures.

uuid

eventNamestringrequired

The event that counts as a conversion.

whereobject[] | nullrequired

Property conditions the event must meet; null counts every one.

at least 1 item · at most 5 items

3 child attributes

propertystringrequired

The event property key.

1–64 characters

operatorstringrequired

notEquals also matches an event without the property. equals and notEquals compare the property as text, ignoring case and accents.

one of equals, notEquals, gt, gte, lt, lte

valuestringrequired

What to compare with, as text ("pro", "true"); a number ("50") for gt, gte, lt and lte.

up to 255 characters

occurrencestring | nullrequired

first: only the contact's first event of this name; repeat: any after it; null: every one.

one of first, repeat

attributionWindowDurationrequired

How long after a message the event still counts, in days.

2 child attributes

valueintegerrequired: min > 0
unitstringrequired: one of seconds, minutes, hours, days

windowChangedAtstring | nullrequired

When the attribution window was last changed; null if never. A change applies to events processed after it: conversions counted before keep the window they were counted under.

date-time

valuePropertystring | nullrequired

The event property summed as revenue; null counts no value.

currencystring | nullrequired

The revenue's currency, if named.

countedFromstringrequired

The earliest events the goal can count: when it was created, the start of the event history then retained. Events from then on are matched to the sends before them, those tracked before the goal existed included; older ones are gone.

date-time

createdAtstringrequired

date-time

curl -X PATCH https://api.kirora.io/v1/conversion-goals/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributionWindow": {
      "value": 7,
      "unit": "days"
    }
  }'

const response = await fetch('https://api.kirora.io/v1/conversion-goals/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "attributionWindow": {
      "value": 7,
      "unit": "days"
    }
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.patch(
    "https://api.kirora.io/v1/conversion-goals/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "attributionWindow": {
            "value": 7,
            "unit": "days",
        },
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "attributionWindow": {
	    "value": 7,
	    "unit": "days"
	  }
	}`)
	req, err := http.NewRequest("PATCH", "https://api.kirora.io/v1/conversion-goals/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.kirora.io/v1/conversion-goals/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "attributionWindow": {
        "value": 7,
        "unit": "days"
      }
    }
    """,
    Encoding.UTF8,
    "application/json");

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "id": "0192f3d0-7a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "campaignId": null,
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "where": null,
    "occurrence": null,
    "attributionWindow": {
      "value": 7,
      "unit": "days"
    },
    "windowChangedAt": "2026-10-08T10:15:00.000Z",
    "valueProperty": "total",
    "currency": "USD",
    "countedFrom": "2026-07-03T09:30:00.000Z",
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
}