> ## Documentation Index > Fetch the complete documentation index at: https://docs.introw.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a payout batch > Opens a payout run for one period and, optionally, a draft payout for each partner on it. A batch is what the Payouts page lists as a period: it holds one payout per partner, and each partner gets their own commission statement. Use it when a run covers several partners, so they stay one batch instead of one batch each. Pass partnerIds to open every partner's payout in this call, or leave it out and add partners one at a time with POST /api/v1/payouts using the returned batch id. The payouts open empty unless attachPendingLines is set. ## OpenAPI ````yaml /openapi.json post /api/v1/payout-batches openapi: 3.1.0 info: title: Introw API version: '2026-05-20' description: >- Customer-facing API for Introw. Manage partners, delegate commission payout operations to your finance software, embed the partner portal in your product with pre-authenticated sessions, ingest affiliate conversions, and trigger on-demand CRM object syncs. servers: - url: https://api.introw.io - url: https://api.staging.introw.io security: - ApiKeyAuth: [] tags: - name: Partners description: >- Read and manage partners for the organisation associated with the authenticated API key. - name: Payouts description: >- Read and update commission payouts. Delegate approval, scheduling, and payment status to your ERP or accounts-payable stack. - name: Commission lines description: >- Create, read, update, decline, and detach commission line items. Lines can live in the pending pool or be attached to a payout. - name: Collaboration description: >- Post comments on partner portals, deals, tasks, form submissions, and payouts, with rich text, internal visibility, and thread replies. Comments trigger the same notifications, workflows, and CRM note sync as comments posted in the app. - name: Forms description: >- Submit Introw forms server-to-server. Register deals, share leads, or file any other form submission from your own systems; submissions run the exact same automation and acceptance pipeline as portal submissions. Read a form's field schema first to discover the field ids, value shapes, and allowed values to send. - name: Auth description: >- Create pre-authenticated partner portal sessions. Exchange a visitor email for a short-lived, single-use portal URL that you embed in an iframe inside your own product: one login, fully branded, no login screen for the partner. - name: Affiliate description: >- Ingest affiliate conversions from your backend or directly from the browser via affiliate.js. Every conversion is anchored to a signed, server-side click token (the first-party `_introw_aff` cookie), deduplicated, and mapped onto a campaign form submission, so attribution cannot be forged or double-counted. - name: CRM description: >- Trigger on-demand syncs of individual CRM objects. Introw already syncs every object automatically about every 15 minutes; use this only when a change must be reflected in Introw immediately, e.g. a workflow mutated the record and its result must persist in Introw right away. paths: /api/v1/payout-batches: post: tags: - Payouts summary: Create a payout batch description: >- Opens a payout run for one period and, optionally, a draft payout for each partner on it. A batch is what the Payouts page lists as a period: it holds one payout per partner, and each partner gets their own commission statement. Use it when a run covers several partners, so they stay one batch instead of one batch each. Pass partnerIds to open every partner's payout in this call, or leave it out and add partners one at a time with POST /api/v1/payouts using the returned batch id. The payouts open empty unless attachPendingLines is set. operationId: createPayoutBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayoutBatchBody' example: periodStart: '2026-01-01T00:00:00.000Z' periodEnd: '2026-03-31T23:59:59.000Z' partnerIds: - ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8 - ptn_02JWL7Z9A9R8K9K9K9K9K9K9K9 responses: '201': description: Payout batch created successfully. content: application/json: schema: $ref: '#/components/schemas/PayoutBatchResponse' example: data: id: pbt_9h8g7f6e5d4c3b2a1z0w9v8u periodStart: '2026-01-01T00:00:00.000Z' periodEnd: '2026-03-31T23:59:59.000Z' payouts: - payoutId: pay_2x7n4q8z0w1a2b3c4d5e6f7g partnerId: ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8 - payoutId: pay_3y8o5r9a1x2b3c4d5e6f7g8h partnerId: ptn_02JWL7Z9A9R8K9K9K9K9K9K9K9 headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string '401': description: API key is missing, invalid, expired, or revoked. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string '402': description: >- Monthly API credit allowance reached. Credits reset at the start of the next calendar month. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string retry-after: description: >- Seconds until the API credit allowance resets (the start of the next calendar month). schema: type: string '403': description: API key does not include the commissions:write scope. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string '404': description: >- One or more partners were not found in the authenticated organisation. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string '422': description: >- Request body failed validation, the period is inverted, or commissions are not set up for the organisation. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' headers: x-ratelimit-limit-minute: description: Maximum number of requests allowed in the current minute. schema: type: string x-ratelimit-remaining-minute: description: Number of requests remaining in the current minute. schema: type: string x-introw-credits-limit-month: description: >- This month's API credit allowance. Absent when the request was not metered (for example an authentication failure) or when the allowance is unlimited. schema: type: string x-introw-credits-remaining-month: description: >- API credits left in the current calendar month, after this request. `0` on a `402`. Absent when the request was not metered or when the allowance is unlimited. schema: type: string components: schemas: CreatePayoutBatchBody: type: object properties: periodStart: type: string format: date-time 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))$ description: Start of the commission period the batch covers. periodEnd: type: string format: date-time 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))$ description: >- End of the commission period the batch covers. Must be on or after periodStart. partnerIds: description: >- Partners to open a draft payout for. Omit to create the batch empty and add partners later with POST /payouts. type: array items: type: string minLength: 1 attachPendingLines: description: >- Attach each partner's pending commission lines whose period overlaps this one, the way creating a payout run in the app does. Defaults to false, so the payouts open empty and you attach lines yourself with POST /commission-lines. type: boolean required: - periodStart - periodEnd additionalProperties: false PayoutBatchResponse: type: object properties: data: type: object properties: id: type: string description: Introw payout batch identifier. periodStart: type: string format: date-time 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))$ description: Start of the commission period the batch covers. periodEnd: type: string format: date-time 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))$ description: End of the commission period the batch covers. payouts: type: array items: type: object properties: payoutId: type: string description: Introw payout identifier. partnerId: type: string description: Partner the payout belongs to. required: - payoutId - partnerId additionalProperties: false description: >- The batch's payouts, one per partner. Empty when the batch was opened without partners. required: - id - periodStart - periodEnd - payouts additionalProperties: false required: - data additionalProperties: false PublicApiError: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code. message: type: string description: Human-readable error message. details: description: Optional structured details for validation and debugging. required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Introw API key shown once when the credential is created. ````