Evaluate incentive/decision rules for a profile event

Runs the incentive decision pipeline for one profile + event and returns a synchronous summary of matched rules; the actual effects (e.g. coupon grants) are queued asynchronously.

Profile traits are loaded from identified_users.traits_masked (same store as PUT /api/v1/profile) and shallow-merged with any inline traits in the body (inline wins, not persisted).

Auth: X-API-Key with scope decide OR decision:call (x-required-scope: decide|decision:call). projectId in the body must match the key’s project.

Rate limit: 30 req/min per (projectId, IP) — over → 429.

Authorizations

ApiKeyAuth

Request Body^required

application/json

object

projectId

required

Must match the API key’s project (tenant isolation).

string

profileId

required

The user/profile ID whose traits are loaded for evaluation.

string

event

required

object

name

required

string

props

object

key

additional properties

any

traits

Optional inline traits merged over the stored profile for THIS decision only (not persisted).

object

key

additional properties

any

userFeatures

Optional feature snapshot for offer-selection. When omitted, minimal null defaults are used.

object

valueScore

number | null

payingAtRisk

boolean

attributionChannelQuality

number | null

historicalRedemptionRate

number | null

Example

1
{
2
  "projectId": "prj_123",
3
  "profileId": "uid_456",
4
  "event": {
5
    "name": "checkout_abandoned",
6
    "props": {
7
      "cartValue": 12000
8
    }
9
  }
10
}

Responses

200

Decision result. matched is empty when no rule fired.

application/json

object

decisionId

required

string

matched

required

Array<object>

object

ruleId

string

effects

Array<object>

object

type

string

summary

string

400

Invalid JSON or missing required fields.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "invalid_json"
3
}

1
{
2
  "error": "missing_required_fields"
3
}

401

Missing/invalid API key.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example^generated

1
{
2
  "error": "example",
3
  "retryAfter": 1,
4
  "message": "example",
5
  "affectedIndices": [
6
    1
7
  ]
8
}

403

API key lacks the decide/decision:call scope.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example^generated

1
{
2
  "error": "example",
3
  "retryAfter": 1,
4
  "message": "example",
5
  "affectedIndices": [
6
    1
7
  ]
8
}

404

Project not found or key belongs to a different project (tenant isolation).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "not_found"
3
}

429

Rate limit exceeded (30/min per project+IP).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "rate_limited"
3
}

503

Decision cache/service binding unavailable.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "service_unavailable"
3
}

POST

/api/v1/decide

1
curl --request POST \
2
  --url https://api.retidal.com/api/v1/decide \
3
  --header 'Content-Type: application/json' \
4
  --header 'X-API-Key: <YOUR_API_KEY>' \
5
  --data '{
6
  "projectId": "prj_123",
7
  "profileId": "uid_456",
8
  "event": {
9
    "name": "checkout_abandoned",
10
    "props": {
11
      "cartValue": 12000
12
    }
13
  }
14
}'

1
const url = 'https://api.retidal.com/api/v1/decide';
2
const options = {
3
  method: 'POST',
4
  headers: {'X-API-Key': '<YOUR_API_KEY>', 'Content-Type': 'application/json'},
5
  body: '{"projectId":"prj_123","profileId":"uid_456","event":{"name":"checkout_abandoned","props":{"cartValue":12000}}}'
6
};
7

8
try {
9
  const response = await fetch(url, options);
10
  const data = await response.json();
11
  console.log(data);
12
} catch (error) {
13
  console.error(error);
14
}

1
import requests
2

3
url = "https://api.retidal.com/api/v1/decide"
4

5
payload = {
6
    "projectId": "prj_123",
7
    "profileId": "uid_456",
8
    "event": {
9
        "name": "checkout_abandoned",
10
        "props": { "cartValue": 12000 }
11
    }
12
}
13
headers = {
14
    "X-API-Key": "<YOUR_API_KEY>",
15
    "Content-Type": "application/json"
16
}
17

18
response = requests.post(url, json=payload, headers=headers)
19

20
print(response.json())

1
import httpx
2
import json
3

4
url = "https://api.retidal.com/api/v1/decide"
5

6
headers = {"X-API-Key": "<YOUR_API_KEY>"}
7

8
payload = json.loads("{\n  \"projectId\": \"prj_123\",\n  \"profileId\": \"uid_456\",\n  \"event\": {\n    \"name\": \"checkout_abandoned\",\n    \"props\": {\n      \"cartValue\": 12000\n    }\n  }\n}")
9

10
response = httpx.post(url, headers=headers, json=payload)
11

12
print(response.json())

1
package main
2

3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io"
8
)
9

10
func main() {
11

12
  url := "https://api.retidal.com/api/v1/decide"
13

14
  payload := strings.NewReader("{\n  \"projectId\": \"prj_123\",\n  \"profileId\": \"uid_456\",\n  \"event\": {\n    \"name\": \"checkout_abandoned\",\n    \"props\": {\n      \"cartValue\": 12000\n    }\n  }\n}")
15

16
  req, _ := http.NewRequest("POST", url, payload)
17

18
  req.Header.Add("X-API-Key", "<YOUR_API_KEY>")
19
  req.Header.Add("Content-Type", "application/json")
20

21
  res, _ := http.DefaultClient.Do(req)
22

23
  defer res.Body.Close()
24
  body, _ := io.ReadAll(res.Body)
25

26
  fmt.Println(res)
27
  fmt.Println(string(body))
28

29
}

200Decision result. matched is empty when no rule fired.

1
{
2
  "decisionId": "dec_abc",
3
  "matched": [
4
    {
5
      "ruleId": "rule_1",
6
      "effects": [
7
        {
8
          "type": "grant_coupon",
9
          "summary": "5% off next order"
10
        }
11
      ]
12
    }
13
  ]
14
}

Evaluate incentive/decision rules for a profile event

Authorizations

Request Bodyrequired

Example

Responses

200

400

Examples

401

Examplegenerated

403

Examplegenerated

404

Example

429

Example

503

Example

Request Body^required

Example^generated

Example^generated