Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nippy.la/llms.txt

Use this file to discover all available pages before exploring further.

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

​
name
string
required
Internal campaign name. Only visible in your console.
​
webhookUrl
string
required
Your backend URL where Nippy will send events. Must be HTTPS.
​
webhookSecret
string
required
Secret for verifying the HMAC-SHA256 webhook signature. Minimum 16 characters.
​
spinsAllowed
number
default:"1"
Maximum spins per user. Use -1 for unlimited.
​
cooldownMinutes
number
default:"0"
Wait time between spins for the same user. Use 0 for no cooldown.
​
gifts
array
required
List of available prizes. Probabilities must add up to exactly 100.

​
Prize types

TypeDescriptionAdditional fields
won_pointsCredits points to the userpointsValue (required)
lostNo prize — needed so probabilities sum to 100—
won_digitalDigital prize (code, voucher, etc.)Descriptive name
won_physicalPhysical prize with tracked inventoryDescriptive 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

OperatorMeaning
gtGreater than
gteGreater than or equal to
ltLess than
lteLess than or equal to
eqEqual to

​
Available actions

ActionDescription
unlock_spinTriggers an automatic spin for the user. The result arrives via the spin.completed webhook.
grant_pointsCredits 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
  }
]