Track a purchase

After a player completes a purchase while supporting a creator, send the transaction to Nexus from your backend so it can be attributed and reported. Authenticate with your program-scoped private key.

Caution

You should only call this after a purchase is confirmed. In most integrations this is triggered from the backend after the payment provider sends a “success” event.

Required fields

Field	Type	Notes
code	string	A previously validated creator code
transactionId	string	Must be unique. Use a receipt or order id from your PSP
subtotal	integer	Pass minor units (USD 9.99 → 999)
currency	enum	ISO code (USD, EUR, JPY, …)
description	string	SKU or product descriptor
transactionDate	RFC3339 string	Timestamp of purchase in ISO format

Recommended fields

Field	Type	Notes
playerId	string	Strongly recommended. Ties purchases to the same player. Pseudonymize (GUID or hashed id); no PII.
playerName	string	Optional, may also be pseudonymized. Shown to creators if present.
metrics	object	Optional but crucial for program analytics (see below).

Note

Send playerId even though the API does not require it. metrics describes a single purchase, while playerId is what ties purchases to the same person over time. Without it Nexus cannot separate a repeat buyer from a new one, and the conversion and reactivation outcomes never resolve.

It only needs to be unique and stable for each player, not the id you use internally. If you treat that id as PII, send a hash or a GUID instead, as long as the same player always gets the same value. Nexus never needs the real one. See Performance metrics for what Nexus derives from it.

Request example (curl)

POST/attributions/transactions

View full referenceParameters, responses, and status codes.

curl -X POST "$NEXUS_BASE_URL/attributions/transactions" \
  -H "Content-Type: application/json" \
  -H "X-SHARED-SECRET: $NEXUS_PRIVATE_KEY" \
  -d '{
    "code": "thesearing",
    "subtotal": 199,
    "currency": "USD",
    "description": "bundle_100_gems",
    "transactionId": "order-123",
    "transactionDate": "2025-10-16T13:01:44.000Z",
    "playerId": "6f10c7f4-psd-123",
    "playerName": "CoolGuy1",
    "metrics": {
      "joinDate": "2017-07-22T17:32:28Z",
      "conversion": {
        "lastPurchaseDate": "2025-01-22T17:32:28Z",
        "totalSpendToDate": {
          "total": 12999,
          "currency": "USD"
        }
      }
    }
  }'

The response is 200 OK and indicates the attribution was accepted.

About metrics

Metrics are optional in the request but crucial for reporting. They power insights such as:

• new player acquisition
• reactivation of churned players
• conversion from free to paid users
• long-term creator influence (LTV impact)
• SKU-based revenue share analytics

If you have access to this data at time of purchase, include it. Otherwise you can add fields later once available.

playerId is not part of metrics, but every outcome above depends on it. Nexus counts a player as Converted at most once ever, and treats a later gap as a Repeat Reactivation only by checking that player’s own history. Both need a stable identifier to attach that history to, so send metrics and playerId together or the reporting they feed stays incomplete.