Gameplay Minutes Reconciliation

Attribute revenue to game developers based on how much time players spend in each game. Generate monthly rollups of gameplay minutes, map games to revenue-sharing SKUs, and create distributions to pay developers their share.

Prerequisites

• A platform with at least one game configured
• Platform API key with scopes: gameplay:event:create, gameplay:rollup:read, gameplay:rollup:generate, gameplay:rollup:confirm
• Reconciliation SKUs and payees configured in the Pay dashboard

Step 1: Record Gameplay Events

Throughout the month, record gameplay_minutes events as players play. Each event records gameplay activity for a user in a specific game.

curl -X POST \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "pvu_a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d",
    "gameId": "game_001",
    "eventName": "gameplay_minutes",
    "description": "30 minutes of gameplay"
  }' \
  https://<host>/api/v1/platform/gameplay/events

See the Record Gameplay Event API reference for full parameter details.

Step 2: Generate a Monthly Rollup

At month-end, generate a rollup that aggregates all gameplay minutes for the period into a per-game breakdown with share percentages.

curl -X POST \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period": "2026-05"}' \
  https://<host>/api/v1/platform/gameplay/rollup

Response

{
  "rollup": {
    "_id": "...",
    "period": "2026-05",
    "status": "draft",
    "totalMinutes": 1200,
    "games": [
      { "gameId": "game_001", "gameName": "Space Blasters", "minutes": 720, "share": 0.6 },
      { "gameId": "game_002", "gameName": "Puzzle Quest", "minutes": 480, "share": 0.4 }
    ]
  }
}

Regenerating

You can regenerate a draft rollup at any time (e.g., if late events were recorded). The existing draft is overwritten with fresh data. Confirmed rollups cannot be regenerated.

Step 3: Map Games to SKUs

Each game in the rollup must be mapped to a reconciliation SKU before confirming. SKUs define how revenue is split between recipients (developers, publishers, etc.). This step is done in the Pay Dashboard under Reconciliation → Gameplay.

Dashboard Workflow

1. Click into a rollup from the Gameplay list
2. For each unmapped game, click Map to open the SKU modal
3. Either select an existing SKU or create a new one with revenue splits (e.g., 70% to developer, 30% to platform)

Auto-matching

If a SKU's external ID matches the game ID and has the gameplay_minutes platform hint, the system suggests it automatically. Click Confirm matches to apply all suggestions at once.

Step 4: Confirm and Distribute

Once all games are mapped, confirm the rollup to lock it and optionally create a distribution.

Via Dashboard (Recommended)

1. On the rollup detail page, click Confirm & Distribute
2. Enter the total dollar amount to distribute for this period
3. Review the recipient summary showing how funds will be split
4. Click Confirm

The system locks the rollup and creates a draft distribution with per-recipient amounts calculated from each game's minute share multiplied by SKU splits.

Via API (Confirm Only)

The API confirms the rollup but does not create a distribution. Use the Pay dashboard to create a distribution from an API-confirmed rollup.

curl -X POST \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period": "2026-05"}' \
  https://<host>/api/v1/platform/gameplay/rollup/confirm

Step 5: Process the Distribution

After confirming, a draft distribution appears in Team Payouts → History. From there:

1. Review the distribution line items and recipient amounts
2. Promote the distribution to initiate payouts
3. Track payout status per recipient

See the Platform Payouts guide for details on the distribution processing flow.

Viewing Rollups

# List all rollups
curl -H "Authorization: Bearer $PLATFORM_KEY" \
  https://<host>/api/v1/platform/gameplay/rollup

# Filter by status
curl -H "Authorization: Bearer $PLATFORM_KEY" \
  "https://<host>/api/v1/platform/gameplay/rollup?status=draft"

# Get a specific period
curl -H "Authorization: Bearer $PLATFORM_KEY" \
  "https://<host>/api/v1/platform/gameplay/rollup?period=2026-05"

Required API Scopes

Error Reference