Skip to main content

Grant a reward (for an action that occurred in the partner's own systems.)

POST 
/api/rewards/grant

Requires admin token. Mints a reward (in Confirmed state, immediately claimable) against a user for an action that happened outside Ownli — for example a device purchase, app migration, or completed referral tracked in the partner's backend. The reward then surfaces in the standard list/claim endpoints.

Idempotency: the supplied clientReference is unique per partner; a repeat call with the same clientReference returns the existing reward instead of minting a new one. A repeat with a different userId or amount returns 409 — guard against accidental key reuse.

Request​

Body

required

    userId stringrequired

    Id of the user receiving the reward.

    amount doublerequired

    Possible values: >= 1 and <= 100

    Reward amount in dollars. Must be >= 1.00 and <= 100.00.

    actionCode stringrequired

    Possible values: <= 64 characters, Value must match regular expression [a-zA-Z0-9._-]+

    Partner-chosen label identifying the action that triggered this reward. Free-form, no Ownli-side validation. Used purely for grouping and reporting.

    clientReference stringrequired

    Possible values: <= 128 characters

    Caller-supplied unique reference for this grant (e.g. their order id or transaction id). Used for idempotency: a repeat call with the same value returns the existing reward instead of minting a new one.

Responses​

Reward granted (or existing reward returned for an idempotent replay).

Schema

    id string

    Id of the granted reward (XT_*).

    userId string

    Id of the user who received the reward.

    amount double

    Reward amount in dollars.

    type string

    Reward type. Always Custom for grant-reward calls.

    actionCode string

    Partner-supplied actionCode echoed back.

    clientReference string

    Partner-supplied clientReference echoed back.

    status string

    Status of the reward. Grant-reward calls always create the reward in Confirmed state so it is immediately claimable.

    dateRewarded string

    ISO-8601 timestamp at which the reward was created.

    idempotentReplay boolean

    True when this call returned an existing reward (idempotent replay) rather than minting a new one.

Loading...