Settlement API

Review monthly settlements, inspect line items, and dispute discrepancies. Reading requires settlement:read; disputes require settlement:dispute. Because every endpoint handles real financial data, it accepts only nsp_live_ Production keys; Sandbox returns 403 production_key_required. Partners can see issued states from pending_review onward, while internal draft and calculated work is hidden.

Endpoints

Method	Path	Scope	Purpose
GET	`/settlements`	`settlement:read`	List settlements, filterable by status and updated_since.
GET	`/settlements/{id}`	`settlement:read`	Settlement detail.
GET	`/settlements/{id}/items`	`settlement:read`	Line items by title, episode, and country.
POST	`/settlements/{id}/dispute`	`settlement:dispute`	Open a dispute.

List and detail

curl "https://signal-partners.newunivers.ai/v1/settlements?status=approved&updated_since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"

{
  "data": [
    {
      "settlement_id": "stl_2026_05",
      "period": "2026-05",
      "currency": "USD",
      "gross_revenue": 120000.00,
      "net_revenue": 76100.00,
      "nu_share": 49465.00,
      "partner_share": 26635.00,
      "status": "approved",
      "updated_at": "2026-06-24T00:00:00Z"
    }
  ]
}

The list returns a summary per settlement. Retrieve one settlement to see all deductions.

{
  "data": {
    "settlement_id": "stl_2026_05",
    "period": "2026-05",
    "currency": "USD",
    "gross_revenue": 120000.00,
    "refunds": 1500.00,
    "platform_fee": 12000.00,
    "payment_processing_fee": 3400.00,
    "tax_withholding": 2000.00,
    "mg_recouped": 25000.00,
    "net_revenue": 76100.00,
    "nu_share": 49465.00,
    "partner_share": 26635.00,
    "rights_holder_share": 0.00,
    "status": "approved",
    "updated_at": "2026-06-24T00:00:00Z"
  }
}

Settlement fields

Field	Meaning
`gross_revenue`	Gross revenue from settlement-eligible events
`refunds`	Reversals from negative revenue events
`platform_fee`	NU platform fee
`payment_processing_fee`	Payment processing costs
`tax_withholding`	Tax withheld
`mg_recouped`	Minimum guarantee recouped in the period
`net_revenue`	Revenue after refunds, fees, tax, and MG recoupment
`nu_share / partner_share`	Allocation of net_revenue under the agreement’s revenue-share rate
`rights_holder_share`	Rights holder’s share of net_revenue; detail only

Deduction fields (refunds, platform_fee, payment_processing_fee, tax_withholding, mg_recouped, and rights_holder_share) are returned only by the detail endpoint, not the list.

period uses the YYYY-MM format.

Settlement items

curl "https://signal-partners.newunivers.ai/v1/settlements/stl_2026_05/items" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"

{
  "data": [
    {
      "settlement_item_id": "sti_001",
      "title_id": "ttl_abc",
      "episode_id": "ep_001",
      "country": "KR",
      "revenue_type": "payment_completed",
      "gross_revenue": 4200.00,
      "net_revenue": 2730.00,
      "nu_share": 1774.50,
      "partner_share": 955.50,
      "rights_holder_share": 0.00
    }
  ]
}

Items break the statement down by title_id, episode_id, country, and revenue_type so you can reconcile it with the events you sent.

Dispute flow

A settlement can be disputed only while disputable: pending_review, approved, or invoiced before the payment deadline. Other states return 409 settlement_not_disputable.

curl -X POST "https://signal-partners.newunivers.ai/v1/settlements/stl_2026_05/dispute" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "KR PAYMENT_COMPLETED count differs from our ledger by ~3%",
    "disputed_amount": 820.00,
    "currency": "USD"
  }'

{
  "data": {
    "dispute_id": "dsp_001",
    "settlement_id": "stl_2026_05",
    "status": "open",
    "reason": "KR PAYMENT_COMPLETED count differs from our ledger by ~3%"
  }
}

NU reviews the dispute and may apply an adjustment in a later settlement.

Stay synchronized (polling)

No webhooks are provided. Poll GET /v1/settlements with updated_since and optionally status to fetch new and changed statements. Each item includes updated_at for use as a cursor.

curl "https://signal-partners.newunivers.ai/v1/settlements?updated_since=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"