Nippy API Platform

Campaigns are the central container for all mechanics. You define the available prizes, their probabilities, user limits, and when they activate.

Create a campaign

POST https://ms.nippy.la/v1/public/campaigns
x-api-key: npk_live_xxx
x-business-id: your-business-id
Content-Type: application/json

{
  "name": "Summer 2026 Campaign",
  "webhookUrl": "https://your-app.com/webhooks/nippy",
  "webhookSecret": "a-secure-secret-min-16-chars",
  "spinsAllowed": 3,
  "cooldownMinutes": 60,
  "gifts": [
    {
      "name": "500 points",
      "type": "won_points",
      "pointsValue": 500,
      "probability": 60
    },
    {
      "name": "100 points",
      "type": "won_points",
      "pointsValue": 100,
      "probability": 30
    },
    {
      "name": "Lose",
      "type": "lost",
      "probability": 10
    }
  ]
}

Response:

{
  "campaignId": "camp-abc123",
  "businessId": "your-business-id",
  "name": "Summer 2026 Campaign",
  "status": "active",
  "createdAt": "2026-05-01T00:00:00.000Z"
}

Parameters

string

required

Internal campaign name. Only visible in your console.

string

required

Your backend URL where Nippy will send events. Must be HTTPS.

string

required

Secret for verifying the HMAC-SHA256 webhook signature. Minimum 16 characters.

number

default:"1"

Maximum spins per user. Use -1 for unlimited.

number

default:"0"

Wait time between spins for the same user. Use 0 for no cooldown.

array

required

List of available prizes. Probabilities must add up to exactly 100.

Prize types

Type	Description	Additional fields
`won_points`	Credits points to the user	`pointsValue` (required)
`lost`	No prize — needed so probabilities sum to 100	—
`won_digital`	Digital prize (code, voucher, etc.)	Descriptive `name`
`won_physical`	Physical prize with tracked inventory	Descriptive `name`

The probabilities of all gifts in a campaign must add up to exactly 100. If they don’t, creation fails with a validation error.

Create activation rules

Rules define which business event triggers a mechanic automatically. When the bank calls nippy.track(), the engine evaluates the campaign’s rules and executes the action if the condition is met.

POST https://ms.nippy.la/v1/public/campaigns/:campaignId/rules
x-api-key: npk_live_xxx
x-business-id: your-business-id
Content-Type: application/json

Rule: unlock spin for purchases over $100

{
  "eventType": "card.purchase.completed",
  "condition": {
    "field": "value",
    "operator": "gt",
    "value": 100
  },
  "action": "unlock_spin"
}

Rule: grant points for purchases over $500

{
  "eventType": "card.purchase.completed",
  "condition": {
    "field": "value",
    "operator": "gte",
    "value": 500
  },
  "action": "grant_points",
  "pointsValue": 200
}

Available condition operators

Operator	Meaning
`gt`	Greater than
`gte`	Greater than or equal to
`lt`	Less than
`lte`	Less than or equal to
`eq`	Equal to

Available actions

Action	Description
`unlock_spin`	Triggers an automatic spin for the user. The result arrives via the `spin.completed` webhook.
`grant_points`	Credits points directly without spinning. Requires the `pointsValue` field.

List campaigns

GET https://ms.nippy.la/v1/public/campaigns
x-api-key: npk_live_xxx
x-business-id: your-business-id

[
  {
    "campaignId": "camp-abc123",
    "name": "Summer 2026 Campaign",
    "status": "active",
    "totalSpins": 1420,
    "totalWins": 987,
    "startsAt": null,
    "endsAt": null
  }
]

Start here

SDK

MCP

Campaigns

Create a campaign

Parameters

Prize types

Create activation rules

Rule: unlock spin for purchases over $100

Rule: grant points for purchases over $500

Available condition operators

Available actions

List campaigns

​Create a campaign

​Parameters

​Prize types

​Create activation rules

​Rule: unlock spin for purchases over $100

​Rule: grant points for purchases over $500

​Available condition operators

​Available actions

​List campaigns

Create a campaign

Parameters

Prize types

Create activation rules

Rule: unlock spin for purchases over $100

Rule: grant points for purchases over $500

Available condition operators

Available actions

List campaigns