Reward Budgets¶

Reward budgets allow operators to cap campaign-level or reward-level usage.

For authentication details and general response format, see the Overview.

Concepts¶

Budgets are attached to one of two owner types:

Campaign
Reward

Supported metric types are:

MonetaryValue
EnrollmentCount
UniquePlayers

Supported enforcement scopes are:

Global
PerPlayer

For MonetaryValue budgets, currencyIsoCode is required. For non-monetary budgets, currencyIsoCode should be omitted or null.

Create Campaign Budget¶

Creates a budget attached to a campaign.

Endpoint: POST /v1/campaigns/{campaignId}/budgets

Path Parameters¶

Parameter	Type	Description
`campaignId`	string	The unique identifier of the campaign.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.
`Content-Type`	string	Yes	Must be `application/json`.

Request Body¶

Field	Type	Required	Description
`metricType`	string	Yes	Budget metric type: `MonetaryValue`, `EnrollmentCount`, or `UniquePlayers`.
`enforcementScope`	string	Yes	Budget enforcement scope: `Global` or `PerPlayer`.
`currencyIsoCode`	string	No	Required when `metricType` is `MonetaryValue`.
`limit`	decimal	Yes	Budget limit value.
`createdBy`	string	Yes	Identifier of who is creating the budget.

Example Request¶

{
  "metricType": "MonetaryValue",
  "enforcementScope": "Global",
  "currencyIsoCode": "EUR",
  "limit": 5000.0,
  "createdBy": "[email protected]"
}

Example Response¶

{
  "message": "OK",
  "data": {
    "id": "bgt-001",
    "operatorId": 1,
    "ownerType": "Campaign",
    "ownerId": "abc123",
    "metricType": "MonetaryValue",
    "enforcementScope": "Global",
    "currencyIsoCode": "EUR",
    "limit": 5000.0,
    "consumed": 0.0,
    "remaining": 5000.0,
    "utilizationPercentage": 0.0,
    "effectiveFromUtc": "2026-03-20T12:00:00Z",
    "createdAtUtc": "2026-03-20T12:00:00Z",
    "createdBy": "[email protected]",
    "updatedAtUtc": null,
    "updatedBy": null,
    "cancelledAtUtc": null,
    "cancelledBy": null
  },
  "responseCode": "OK"
}

Get Campaign Budgets¶

Retrieves all budgets attached to a campaign.

Endpoint: GET /v1/campaigns/{campaignId}/budgets

Path Parameters¶

Parameter	Type	Description
`campaignId`	string	The unique identifier of the campaign.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.

Response¶

Returns an array of budget summary objects in the data field.

Create Reward Budget¶

Creates a budget attached to a reward.

Endpoint: POST /v1/rewards/{rewardId}/budgets

Path Parameters¶

Parameter	Type	Description
`rewardId`	string	The unique identifier of the reward.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.
`Content-Type`	string	Yes	Must be `application/json`.

Request Body¶

Uses the same schema as Create Campaign Budget.

Example Request¶

{
  "metricType": "MonetaryValue",
  "enforcementScope": "PerPlayer",
  "currencyIsoCode": "EUR",
  "limit": 100.0,
  "createdBy": "[email protected]"
}

Example Response¶

The response has the same shape as the campaign budget response, but ownerType is Reward and ownerId is the reward ID.

Get Reward Budgets¶

Retrieves all budgets attached to a reward.

Endpoint: GET /v1/rewards/{rewardId}/budgets

Path Parameters¶

Parameter	Type	Description
`rewardId`	string	The unique identifier of the reward.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.

Response¶

Returns an array of budget summary objects in the data field.

Get Budget by ID¶

Retrieves a specific budget by its ID.

Endpoint: GET /v1/budgets/{budgetId}

Path Parameters¶

Parameter	Type	Description
`budgetId`	string	The unique identifier of the budget.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.

Response¶

Returns a single budget summary object in the data field.

Cancel Budget¶

Cancels a budget.

Endpoint: POST /v1/budgets/{budgetId}/cancel

Path Parameters¶

Parameter	Type	Description
`budgetId`	string	The unique identifier of the budget to cancel.

Request Headers¶

Header	Type	Required	Description
`X-AUTH-OPERATOR-ID`	integer	Yes	The operator ID.
`X-AUTH-REQUEST-HASH`	string	Yes	The computed SHA-256 authentication hash.
`Content-Type`	string	Yes	Must be `application/json`.

Request Body¶

Field	Type	Required	Description
`cancelledBy`	string	Yes	Identifier of who is cancelling this budget.

Example Request¶

{
  "cancelledBy": "[email protected]"
}

Example Response¶

{
  "message": "OK",
  "data": {},
  "responseCode": "OK"
}

Budget Response Fields¶

Field	Type	Description
`id`	string	Unique budget identifier assigned by Gamnify.
`operatorId`	integer	The operator this budget belongs to.
`ownerType`	string	The budget owner type: `Campaign` or `Reward`.
`ownerId`	string	The owning campaign or reward ID.
`metricType`	string	The budget metric type.
`enforcementScope`	string	The budget enforcement scope.
`currencyIsoCode`	string (nullable)	Currency code for monetary budgets.
`limit`	decimal	Configured budget limit.
`consumed`	decimal	Amount already consumed.
`remaining`	decimal	Amount remaining.
`utilizationPercentage`	decimal	Percentage of the budget already consumed.
`effectiveFromUtc`	string (date-time)	Time from which the budget is effective.
`createdAtUtc`	string (date-time)	Timestamp when the budget was created.
`createdBy`	string	Who created the budget.
`updatedAtUtc`	string (date-time, nullable)	Timestamp of the last update, if any.
`updatedBy`	string (nullable)	Who last updated the budget, if applicable.
`cancelledAtUtc`	string (date-time, nullable)	Timestamp when the budget was cancelled, if applicable.
`cancelledBy`	string (nullable)	Who cancelled the budget, if applicable.

Validation Notes¶

metricType and enforcementScope must be valid enum values.
currencyIsoCode is required for MonetaryValue budgets.
Missing request bodies and business-rule validation failures currently return the standard error envelope with a 500 status code and an explanatory message.
Invalid enum values are rejected before controller execution and return 400 Bad Request.