Skip to content
Docs

Record transaction

Records one or more transactions against a creator group. The body accepts either a single transaction or an array of them. If the same transactionId appears more than once within one array, every one of those rows is still saved (this is how you split credit for a single purchase across multiple group members); it is only treated as a duplicate against transactions that already exist for your publisher account from an earlier call, which returns a bare 409 with only the default status text, no JSON payload.

Once a request passes validation, subtotal must be a whole number in the smallest denomination of currency (cents for USD), minimum 1. By default (when useLDCurrency is omitted or true), that validated value is also what you send: the request passes through unconverted. total defaults to subtotal when omitted, and totalCurrency defaults to currency when omitted. On creation, status is only honored if it is Normal or Test; any other value, including an omitted one, is stored as Normal.

A currency your creator group has disabled is rejected with 400. None of this operation’s 400 responses include a stable code field: an unresolvable groupId comes back as a bare, unstructured text body, and an unresolvable code/member comes back as a JSON object with only a message.

NOTE: This method uses secret (nexus_sk_...) API keys and should never be called from or embedded into the gaming client. These routes should ONLY be accessed from your back-end services. NOTE: The subtotal passed for a transaction will be in the smallest denomination of the currency.

Authorizations

Section titled “Authorizations”
X-SHARED-SECRET
required
stringheader

Send your secret API key (nexus_sk_...) in the X-SHARED-SECRET header. Generate one in the Publisher Dashboard.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
groupId
string
Example
V1StGXR8_Z5jdHi6B1LiO

Creator group to attribute this transaction to. If your key is scoped to a single program, that group is always used regardless of this value; otherwise falls back to your default group when omitted.

Request Body

Section titled “Request Body”

This route accepts a single transaction or an array of transactions.

Media typeapplication/json
One of:
object
playerName
string
Example
shadowstrike99
id

Nexus-generated id for this attribution record, not your own transactionId.

string
Example
2ixlNNFdJh-9scoXek80w
code
required

The creator code this transaction should be attributed to. The member must have an approved membership in the target group.

string
Example
popcornfrog
memberPlayerId

Your identifier for the creator this transaction was attributed to, from their group membership, not the purchasing player.

string
Example
player_8f2c41d0
description
required
string
Example
1000 gems
status

Initial transaction status. Only Normal or Test is honored on creation; any other value (or omitting this) is stored as Normal.

string
Allowed values: Normal Fraud Refund Chargeback
Example
Normal
subtotal
required

Purchase subtotal, in the smallest denomination of currency (e.g. cents for USD). Must be a whole number of at least 1, once validated; by default that is also what you send.

number format: cents
Example
999
currency
required
string
Allowed values: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTC BTN BWP BYN BYR BZD CAD CDF CHF CLF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XAG XAU XCD XDR XOF XPF YER ZAR ZMK ZMW ZWL
Example
USD
total

Total charged, in the smallest denomination of totalCurrency. Defaults to subtotal if omitted.

number format: cents
Example
999
totalCurrency

Currency for total. Defaults to currency if omitted.

string
Allowed values: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTC BTN BWP BYN BYR BZD CAD CDF CHF CLF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XAG XAU XCD XDR XOF XPF YER ZAR ZMK ZMW ZWL
Example
USD
transactionId
required

Your own idempotency key for this purchase. Reusing one already saved for your publisher account returns a bare 409 with only the default status text, no JSON payload. Reusing one within the same request array is allowed and is how you split one purchase’s credit across multiple members.

string
Example
txn_8f2c41d0
transactionDate
required
string format: date-time
Example
2026-03-13T17:32:28Z
platform
string
Allowed values: PC PlayStation Xbox Switch Apple Android VR
playerId
string
Example
12345
playerName
string
Example
shadowstrike99
metrics

Metrics are optional but will allow Nexus to provide useful statistics about your program

object
joinDate

The date that the player joined your game

string format: date-time
Example
2026-03-13T17:32:28Z
conversion

Conversion metrics are used for calculationg the conversion rate of your customers. Only one of lastPurchaseDate or totalSpendToDate are required. lastPurchaseDate is preferred, but totalSpendToDate can be used if not available

object
lastPurchase
object
date
string format: date-time
Example
2026-03-13T17:32:28Z
platform

The platform where the last purchase was made

string
Example
Android
totalSpendToDate
object
total
required
number
Example
129.99
currency
required
string
Allowed values: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTC BTN BWP BYN BYR BZD CAD CDF CHF CLF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XAG XAU XCD XDR XOF XPF YER ZAR ZMK ZMW ZWL
Example
USD
memberShareAmount

The amount that the member received for this transaction. This will not be specified upon initial transaction creation, as the calculation happens in a separate process.

number
Example
1
memberSharePercent

The percent of the subtotal for this transaction that the member received. if a memberSharePercent is provided upon transaction creation, it will always be used. Otherwise, the percent a member receives will be influenced by factors such as the default group setting, member tier, scheduled revenue shares, spcific skus

number
>= 1 <= 100
Example
10
memberPaid
boolean
Example
false
skuId

Your internal ID for the item that was purchased

string
Example
Hv98bvRCSm1jDDPhls1qC

Responses

Section titled “ Responses ”

200

Section titled “200”

Transaction created. Returns either a single transaction or an array if more than one was included in the request body.

Media typeapplication/json
One of:
object
transaction
object
id

Nexus-generated id for this attribution record, not your own transactionId.

string
code
required

The creator code this transaction should be attributed to. The member must have an approved membership in the target group.

string
memberPlayerId

Your identifier for the creator this transaction was attributed to, from their group membership, not the purchasing player.

string
description
required
string
status

Initial transaction status. Only Normal or Test is honored on creation; any other value (or omitting this) is stored as Normal.

string
Allowed values: Normal Fraud Refund Chargeback
subtotal
required

Purchase subtotal, in the smallest denomination of currency (e.g. cents for USD). Must be a whole number of at least 1, once validated; by default that is also what you send.

number format: cents
currency
required
string
Allowed values: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTC BTN BWP BYN BYR BZD CAD CDF CHF CLF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XAG XAU XCD XDR XOF XPF YER ZAR ZMK ZMW ZWL
total

Total charged, in the smallest denomination of totalCurrency. Defaults to subtotal if omitted.

number format: cents
totalCurrency

Currency for total. Defaults to currency if omitted.

string
Allowed values: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTC BTN BWP BYN BYR BZD CAD CDF CHF CLF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XAG XAU XCD XDR XOF XPF YER ZAR ZMK ZMW ZWL
transactionId
required

Your own idempotency key for this purchase. Reusing one already saved for your publisher account returns a bare 409 with only the default status text, no JSON payload. Reusing one within the same request array is allowed and is how you split one purchase’s credit across multiple members.

string
transactionDate
required
string format: date-time
platform
string
Allowed values: PC PlayStation Xbox Switch Apple Android VR
playerId
string
playerName
string
metrics

Metrics are optional but will allow Nexus to provide useful statistics about your program

object
joinDate

The date that the player joined your game

string format: date-time
conversion

Conversion metrics are used for calculationg the conversion rate of your customers. Only one of lastPurchaseDate or totalSpendToDate are required. lastPurchaseDate is preferred, but totalSpendToDate can be used if not available

object
lastPurchase
object
date
string format: date-time
platform

The platform where the last purchase was made

string
totalSpendToDate
object
total
required
number
currency
required
string
Allowed values: AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTC BTN BWP BYN BYR BZD CAD CDF CHF CLF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VEF VND VUV WST XAF XAG XAU XCD XDR XOF XPF YER ZAR ZMK ZMW ZWL
memberShareAmount

The amount that the member received for this transaction. This will not be specified upon initial transaction creation, as the calculation happens in a separate process.

number
memberSharePercent

The percent of the subtotal for this transaction that the member received. if a memberSharePercent is provided upon transaction creation, it will always be used. Otherwise, the percent a member receives will be influenced by factors such as the default group setting, member tier, scheduled revenue shares, spcific skus

number
>= 1 <= 100
memberPaid
boolean
skuId

Your internal ID for the item that was purchased

string

400

Section titled “400”

Invalid input, object invalid, code not found in group members

409

Section titled “409”

A transaction with this transactionId already exists

POST
/attributions/transactions
curl --request POST \
  --url 'https://api.nexus.gg/v1/attributions/transactions?groupId=V1StGXR8_Z5jdHi6B1LiO' \
  --header 'Content-Type: application/json' \
  --header 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  --data '{ "playerName": "shadowstrike99", "id": "2ixlNNFdJh-9scoXek80w", "code": "popcornfrog", "memberPlayerId": "player_8f2c41d0", "description": "1000 gems", "status": "Normal", "subtotal": 999, "currency": "AED", "total": 999, "totalCurrency": "AED", "transactionId": "txn_8f2c41d0", "transactionDate": "2026-03-13T17:32:28Z", "platform": "PC", "playerId": "12345", "metrics": { "joinDate": "2026-03-13T17:32:28Z", "conversion": { "lastPurchase": { "date": "2026-03-13T17:32:28Z", "platform": "Android" }, "totalSpendToDate": { "total": 129.99, "currency": "AED" } } }, "memberShareAmount": 1, "memberSharePercent": 10, "memberPaid": false, "skuId": "Hv98bvRCSm1jDDPhls1qC" }'
Example
{
  "transaction": {
    "id": "2ixlNNFdJh-9scoXek80w",
    "code": "popcornfrog",
    "memberPlayerId": "player_8f2c41d0",
    "description": "1000 gems",
    "status": "Normal",
    "subtotal": 999,
    "currency": "AED",
    "total": 999,
    "totalCurrency": "AED",
    "transactionId": "txn_8f2c41d0",
    "transactionDate": "2026-03-13T17:32:28Z",
    "platform": "PC",
    "playerId": "12345",
    "playerName": "shadowstrike99",
    "metrics": {
      "joinDate": "2026-03-13T17:32:28Z",
      "conversion": {
        "lastPurchase": {
          "date": "2026-03-13T17:32:28Z",
          "platform": "Android"
        },
        "totalSpendToDate": {
          "total": 129.99,
          "currency": "AED"
        }
      }
    },
    "memberShareAmount": 1,
    "memberSharePercent": 10,
    "memberPaid": false,
    "skuId": "Hv98bvRCSm1jDDPhls1qC"
  }
}