Create a payout

curl --request POST \
  --url https://api.introw.io/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "partnerId": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
  "periodStart": "2026-01-01T00:00:00.000Z",
  "periodEnd": "2026-03-31T23:59:59.000Z"
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    partnerId: 'ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8',
    periodStart: '2026-01-01T00:00:00.000Z',
    periodEnd: '2026-03-31T23:59:59.000Z'
  })
};

fetch('https://api.introw.io/api/v1/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.introw.io/api/v1/payouts"

payload = {
    "partnerId": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
    "periodStart": "2026-01-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.000Z"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "pay_2x7n4q8z0w1a2b3c4d5e6f7g",
    "partner": {
      "id": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
      "name": "Acme Partners"
    },
    "batchId": "pbt_9h8g7f6e5d4c3b2a1z0w9v8u",
    "periodStart": "2026-01-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.000Z",
    "amount": {
      "value": "0.00",
      "currency": "USD"
    },
    "stage": "DRAFT",
    "poNumber": null,
    "metadata": "Remittance reference: ACME-Q1-2026\nBank: paid from our EUR account\n\nQuestions? [email protected]",
    "createdAt": "2026-04-05T09:00:00.000Z",
    "updatedAt": "2026-04-05T09:00:00.000Z"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

Create a payout

Opens a commission payout for one partner and one period, so your finance stack can assemble a payout end to end over the API. The payout is created empty by default: attach lines with POST /commission-lines using the returned payout id, then render the statement with POST /api/v1/payouts//statement. Set attachPendingLines to pull in the partner’s pending lines for the period instead, the way creating a payout in the app does. Every payout belongs to a batch: pass batchId to put this partner on an existing run alongside others, or leave it out and the payout gets a batch of its own. Either way the id comes back on the payout as batchId. Answers 200 instead of 201 when the partner already had a payout on that batch, returning the one they have.

POST

api

payouts

Create a payout

curl --request POST \
  --url https://api.introw.io/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "partnerId": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
  "periodStart": "2026-01-01T00:00:00.000Z",
  "periodEnd": "2026-03-31T23:59:59.000Z"
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    partnerId: 'ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8',
    periodStart: '2026-01-01T00:00:00.000Z',
    periodEnd: '2026-03-31T23:59:59.000Z'
  })
};

fetch('https://api.introw.io/api/v1/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.introw.io/api/v1/payouts"

payload = {
    "partnerId": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
    "periodStart": "2026-01-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.000Z"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "pay_2x7n4q8z0w1a2b3c4d5e6f7g",
    "partner": {
      "id": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
      "name": "Acme Partners"
    },
    "batchId": "pbt_9h8g7f6e5d4c3b2a1z0w9v8u",
    "periodStart": "2026-01-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.000Z",
    "amount": {
      "value": "0.00",
      "currency": "USD"
    },
    "stage": "DRAFT",
    "poNumber": null,
    "metadata": "Remittance reference: ACME-Q1-2026\nBank: paid from our EUR account\n\nQuestions? [email protected]",
    "createdAt": "2026-04-05T09:00:00.000Z",
    "updatedAt": "2026-04-05T09:00:00.000Z"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

Authorizations

x-api-key

string

header

required

Introw API key shown once when the credential is created.

Body

application/json

partnerId

string

required

Introw partner the payout is for.

Minimum string length: 1

periodStart

string<date-time>

required

Start of the commission period the payout covers.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

periodEnd

string<date-time>

required

End of the commission period the payout covers. Must be on or after periodStart.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

batchId

string

Existing batch to open this payout on, so several partners share one payout run. The batch is one period by definition, so it dates the payout and periodStart/periodEnd are ignored. When omitted, the payout gets a batch of its own. A partner already on the batch returns their existing payout instead of a second one.

Minimum string length: 1

stage

enum<string>

Stage to open the payout in. Defaults to DRAFT, which is where the app creates one.

Available options:

DRAFT,

PENDING_REVIEW,

PENDING_INVOICE,

APPROVED,

SCHEDULED,

PENDING_PAYMENT,

PAID,

DECLINED,

POSTPONED,

BLOCKED,

FAILED

poNumber

string | null

Partner purchase order number.

metadata

string | null

Free-text block printed on the commission statement PDF, below the commission table.

Maximum string length: 2000

attachPendingLines

boolean

Attach the partner's pending commission lines whose period overlaps this one, the way creating a payout in the app does. Defaults to false, so the payout opens empty and you attach lines yourself with POST /commission-lines.

Response

Payout created successfully.

data

object

required

Show child attributes

INTROW API

Use cases

Partner API

Forms API

CRM API

Commission payouts API

Commission lines API

Collaboration API

Embed API

Affiliate API

Create a payout

Authorizations

Body

Response