> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate Payrun

> Calculate a DRAFT pay run, MAIN or SUPPLEMENTARY, from the pay items stored in it.

Calculates the run's employees, or the named `employee_ids` among them. A
SUPPLEMENTARY run's employees are those holding pay items in it, and so are a positive
pay MAIN run's. A net change MAIN run's are those holding pay items in it and every
member of its pay group on the pay calendar's pay date that no supplementary run of
the period pays instead, with or without pay items: they are paid from standing
compensation. A run with nobody to calculate is refused (409 `INVALID_TRANSITION`,
`params.reason` `NO_EMPLOYEES`).

A run that is not DRAFT, one being calculated included, is refused with 409
`INVALID_TRANSITION` (`params.reason` `NOT_DRAFT`, `params.from` its status). A MAIN
run first takes its pay calendar's current pay date, refused
(409 `DUPLICATE_DEFINING_ATTRIBUTES`, `params.id` the run holding it) while another run
of the calendar and pay group pays on that date. Answers with the calculation task, as
submit does; the run is PROCESSING until the task completes.

In a SUPPLEMENTARY run, an employee whose earnings total zero or less, or whose net pay
would be negative, is not paid: the task's results carry the error for them and no
payslip is written, so approval is refused until their pay items change. A net pay of
zero on positive earnings is paid, and the Bacs file leaves the employee out.



## OpenAPI

````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/payruns/{payrun_id}/calculate
openapi: 3.2.0
info:
  description: Intermezzo's global payroll apis, organized by country
  summary: Global Payroll Platform
  title: Intermezzo Global Payroll
  version: '2026-11-18'
  x-logo:
    url: /static/icon.svg
servers:
  - description: Preview
    url: https://preview.intermezzo.ai
security: []
paths:
  /gb/organizations/{organization_id}/payruns/{payrun_id}/calculate:
    post:
      tags:
        - Great Britain
        - Pay Runs
      summary: Calculate Payrun
      description: >-
        Calculate a DRAFT pay run, MAIN or SUPPLEMENTARY, from the pay items
        stored in it.


        Calculates the run's employees, or the named `employee_ids` among them.
        A

        SUPPLEMENTARY run's employees are those holding pay items in it, and so
        are a positive

        pay MAIN run's. A net change MAIN run's are those holding pay items in
        it and every

        member of its pay group on the pay calendar's pay date that no
        supplementary run of

        the period pays instead, with or without pay items: they are paid from
        standing

        compensation. A run with nobody to calculate is refused (409
        `INVALID_TRANSITION`,

        `params.reason` `NO_EMPLOYEES`).


        A run that is not DRAFT, one being calculated included, is refused with
        409

        `INVALID_TRANSITION` (`params.reason` `NOT_DRAFT`, `params.from` its
        status). A MAIN

        run first takes its pay calendar's current pay date, refused

        (409 `DUPLICATE_DEFINING_ATTRIBUTES`, `params.id` the run holding it)
        while another run

        of the calendar and pay group pays on that date. Answers with the
        calculation task, as

        submit does; the run is PROCESSING until the task completes.


        In a SUPPLEMENTARY run, an employee whose earnings total zero or less,
        or whose net pay

        would be negative, is not paid: the task's results carry the error for
        them and no

        payslip is written, so approval is refused until their pay items change.
        A net pay of

        zero on positive earnings is paid, and the Bacs file leaves the employee
        out.
      operationId: >-
        calculate_payrun_gb_organizations__organization_id__payruns__payrun_id__calculate_post
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            title: Organization Id
            type: string
        - in: path
          name: payrun_id
          required: true
          schema:
            title: Payrun Id
            type: string
        - in: header
          name: X-Include-Execution-History
          required: false
          schema:
            default: false
            title: X-Include-Execution-History
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayrunCalculateRequest'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePayrollTaskResponse_PayrunStatus_'
          description: Successful Response
        '400':
          content:
            application/json:
              examples:
                ORG_BELONGS_TO_A_DIFFERENT_COUNTRY:
                  summary: >-
                    Raised when an organization belongs to a different country
                    than the one in the path.
                  value:
                    errors:
                      - code: ORG_BELONGS_TO_A_DIFFERENT_COUNTRY
                        message: >-
                          Raised when an organization belongs to a different
                          country than the one in the path.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - ORG_BELONGS_TO_A_DIFFERENT_COUNTRY
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            - `ORG_BELONGS_TO_A_DIFFERENT_COUNTRY`: Raised when an organization
            belongs to a different country than the one in the path.
        '404':
          content:
            application/json:
              examples:
                HUB_NOT_FOUND:
                  summary: >-
                    Raised when a hub does not exist under the parent named in
                    the path.
                  value:
                    errors:
                      - code: HUB_NOT_FOUND
                        message: >-
                          Raised when a hub does not exist under the parent
                          named in the path.
                PAYRUN_NOT_FOUND:
                  summary: Raised when a payrun is not found.
                  value:
                    errors:
                      - code: PAYRUN_NOT_FOUND
                        message: Raised when a payrun is not found.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - HUB_NOT_FOUND
                            - PAYRUN_NOT_FOUND
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            - `HUB_NOT_FOUND`: Raised when a hub does not exist under the parent
            named in the path.

            - `PAYRUN_NOT_FOUND`: Raised when a payrun is not found.
        '409':
          content:
            application/json:
              examples:
                DUPLICATE_DEFINING_ATTRIBUTES:
                  summary: >-
                    Raised when a pay run would take a payment date that another
                    live (not cancelled) run of the same pay calendar and pay
                    group already holds.
                  value:
                    errors:
                      - code: DUPLICATE_DEFINING_ATTRIBUTES
                        message: >-
                          Raised when a pay run would take a payment date that
                          another live (not cancelled) run of the same pay
                          calendar and pay group already holds.
                INVALID_TRANSITION:
                  summary: >-
                    Raised when a pay run that is not DRAFT is changed: pay
                    items added or deleted, the run calculated or cancelled, or
                    employees moved into or out of it.
                  value:
                    errors:
                      - code: INVALID_TRANSITION
                        message: >-
                          Raised when a pay run that is not DRAFT is changed:
                          pay items added or deleted, the run calculated or
                          cancelled, or employees moved into or out of it.
                        params:
                          allowed:
                            - DRAFT
                          from: APPROVED
                          reason: NOT_DRAFT
                          run_id: run_01j0000000e008000000000001
                INVALID_TRANSITION (NO_EMPLOYEES):
                  summary: >-
                    Raised when a pay run has nobody to calculate, or nobody to
                    pay at approval: its population is empty.
                  value:
                    errors:
                      - code: INVALID_TRANSITION
                        message: >-
                          Raised when a pay run has nobody to calculate, or
                          nobody to pay at approval: its population is empty.
                        params:
                          allowed:
                            - DRAFT
                          from: DRAFT
                          reason: NO_EMPLOYEES
                          run_id: run_01j0000000e008000000000001
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - INVALID_TRANSITION
                            - DUPLICATE_DEFINING_ATTRIBUTES
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            - `INVALID_TRANSITION`: Raised when a pay run that is not DRAFT is
            changed: pay items added or deleted, the run calculated or
            cancelled, or employees moved into or out of it.

            - `INVALID_TRANSITION`: Raised when a pay run has nobody to
            calculate, or nobody to pay at approval: its population is empty.

            - `DUPLICATE_DEFINING_ATTRIBUTES`: Raised when a pay run would take
            a payment date that another live (not cancelled) run of the same pay
            calendar and pay group already holds.
        '422':
          content:
            application/json:
              examples:
                CALCULATED_BY_ENGINE:
                  summary: >-
                    A partner pay line uses a wage type the engine pays for one
                    of the employee's absences.
                  value:
                    errors:
                      - code: CALCULATED_BY_ENGINE
                        message: >-
                          A partner pay line uses a wage type the engine pays
                          for one of the employee's absences.
                GB_SMP_AWE_REVISION_MALFORMED:
                  summary: >-
                    An already-paid absence line's record of what priced it
                    cannot be read.
                  value:
                    errors:
                      - code: GB_SMP_AWE_REVISION_MALFORMED
                        message: >-
                          An already-paid absence line's record of what priced
                          it cannot be read.
                GB_SMP_COMPENSATION_HISTORY_GAP:
                  summary: >-
                    A pay rise needs the maternity pay recalculated, and the
                    employee's salary history does not reach back over the
                    earnings it averages.
                  value:
                    errors:
                      - code: GB_SMP_COMPENSATION_HISTORY_GAP
                        message: >-
                          A pay rise needs the maternity pay recalculated, and
                          the employee's salary history does not reach back over
                          the earnings it averages.
                GB_SMP_JOB_DATES_MALFORMED:
                  summary: >-
                    A pay rise needs the maternity pay recalculated, and a job
                    record's employment start or end date cannot be read.
                  value:
                    errors:
                      - code: GB_SMP_JOB_DATES_MALFORMED
                        message: >-
                          A pay rise needs the maternity pay recalculated, and a
                          job record's employment start or end date cannot be
                          read.
                GB_SMP_LINE_META_VERSION_UNKNOWN:
                  summary: >-
                    An already-paid absence line carries a
                    `content_schema_version` this deploy does not read.
                  value:
                    errors:
                      - code: GB_SMP_LINE_META_VERSION_UNKNOWN
                        message: >-
                          An already-paid absence line carries a
                          `content_schema_version` this deploy does not read.
                INVALID_REFERENCE:
                  summary: >-
                    Raised when a request names employees outside the pay run's
                    population: the employees with DRAFT pay elements in it and,
                    for a MAIN run of a net change pay group, the members of its
                    pay group that no supplementary run of the period owns.
                  value:
                    errors:
                      - code: INVALID_REFERENCE
                        message: >-
                          Raised when a request names employees outside the pay
                          run's population: the employees with DRAFT pay
                          elements in it and, for a MAIN run of a net change pay
                          group, the members of its pay group that no
                          supplementary run of the period owns.
                NOTHING_TO_PAY:
                  summary: >-
                    Raised when a calculation is requested for employees whose
                    pay items in the run cannot make a payment: in a
                    supplementary run, no earning (`params.reason` `NO_EARNING`:
                    a supplementary pays additional earnings, never deductions,
                    benefits or reimbursements alone); in a positive pay main
                    run, deductions alone (`DEDUCTIONS_ONLY`).
                  value:
                    errors:
                      - code: NOTHING_TO_PAY
                        message: >-
                          Raised when a calculation is requested for employees
                          whose pay items in the run cannot make a payment: in a
                          supplementary run, no earning (`params.reason`
                          `NO_EARNING`: a supplementary pays additional
                          earnings, never deductions, benefits or reimbursements
                          alone); in a positive pay main run, deductions alone
                          (`DEDUCTIONS_ONLY`).
                PAY_PERIOD_UNRESOLVED:
                  summary: >-
                    Raised when a payrun's pay date and period type cannot be
                    mapped to a tax period — either the period type is one the
                    tax calendar does not support, or the pay date falls outside
                    the tax year.
                  value:
                    errors:
                      - code: PAY_PERIOD_UNRESOLVED
                        message: >-
                          Raised when a payrun's pay date and period type cannot
                          be mapped to a tax period — either the period type is
                          one the tax calendar does not support, or the pay date
                          falls outside the tax year.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - INVALID_REFERENCE
                            - NOTHING_TO_PAY
                            - PAY_PERIOD_UNRESOLVED
                            - CALCULATED_BY_ENGINE
                            - GB_SMP_LINE_META_VERSION_UNKNOWN
                            - GB_SMP_AWE_REVISION_MALFORMED
                            - GB_SMP_COMPENSATION_HISTORY_GAP
                            - GB_SMP_JOB_DATES_MALFORMED
                            - FIELD_REQUIRED
                            - FIELD_INVALID_TYPE_STRING
                            - FIELD_INVALID_TYPE_INT
                            - FIELD_INVALID_TYPE_FLOAT
                            - FIELD_INVALID_TYPE_BOOL
                            - FIELD_INVALID_TYPE_DICT
                            - FIELD_INVALID_TYPE_LIST
                            - FIELD_STRING_TOO_SHORT
                            - FIELD_STRING_TOO_LONG
                            - FIELD_STRING_PATTERN_MISMATCH
                            - FIELD_VALUE_TOO_SMALL
                            - FIELD_VALUE_TOO_LARGE
                            - FIELD_INVALID_DATE
                            - FIELD_INVALID_DATETIME
                            - FIELD_INVALID_TIME
                            - FIELD_INVALID_DATE_FORMAT
                            - FIELD_INVALID_DATETIME_FORMAT
                            - FIELD_INVALID_ENUM_VALUE
                            - FIELD_INVALID_EMAIL
                            - FIELD_INVALID_URL
                            - FIELD_LIST_TOO_SHORT
                            - FIELD_LIST_TOO_LONG
                            - FIELD_UNKNOWN
                            - FIELD_VALIDATION_ERROR
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            The request failed validation. Type and format errors use the
            generic FIELD_* codes.

            - `INVALID_REFERENCE`: Raised when a request names employees outside
            the pay run's population: the employees with DRAFT pay elements in
            it and, for a MAIN run of a net change pay group, the members of its
            pay group that no supplementary run of the period owns.

            - `NOTHING_TO_PAY`: Raised when a calculation is requested for
            employees whose pay items in the run cannot make a payment: in a
            supplementary run, no earning (`params.reason` `NO_EARNING`: a
            supplementary pays additional earnings, never deductions, benefits
            or reimbursements alone); in a positive pay main run, deductions
            alone (`DEDUCTIONS_ONLY`).

            - `PAY_PERIOD_UNRESOLVED`: Raised when a payrun's pay date and
            period type cannot be mapped to a tax period — either the period
            type is one the tax calendar does not support, or the pay date falls
            outside the tax year.

            - `CALCULATED_BY_ENGINE`: A partner pay line uses a wage type the
            engine pays for one of the employee's absences.

            - `GB_SMP_LINE_META_VERSION_UNKNOWN`: An already-paid absence line
            carries a `content_schema_version` this deploy does not read.

            - `GB_SMP_AWE_REVISION_MALFORMED`: An already-paid absence line's
            record of what priced it cannot be read.

            - `GB_SMP_COMPENSATION_HISTORY_GAP`: A pay rise needs the maternity
            pay recalculated, and the employee's salary history does not reach
            back over the earnings it averages.

            - `GB_SMP_JOB_DATES_MALFORMED`: A pay rise needs the maternity pay
            recalculated, and a job record's employment start or end date cannot
            be read.
      security:
        - BearerToken: []
components:
  schemas:
    PayrunCalculateRequest:
      additionalProperties: false
      properties:
        employee_ids:
          anyOf:
            - items:
                type: string
              minItems: 1
              type: array
            - type: 'null'
          description: >-
            The employees to calculate, each one of the run's employees. Omit to
            calculate all of them. A SUPPLEMENTARY run's employees are those
            holding pay items in it, and so are a positive pay MAIN run's. A net
            change MAIN run's are those holding pay items in it and the members
            of its pay group that no supplementary run of the period pays
            instead, paid from standing compensation.
          title: Employee Ids
        message:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          description: >-
            Employer message for this payrun, shown on every payslip it
            produces. Omit to keep the message of the run's current payslips
            (the most recently calculated one's, if they differ).
          title: Message
      title: PayrunCalculateRequest
      type: object
    CreatePayrollTaskResponse_PayrunStatus_:
      additionalProperties: false
      properties:
        payroll_status_id:
          title: Payroll Status Id
          type: string
        status:
          $ref: '#/components/schemas/PayrunStatus'
        task_id:
          title: Task Id
          type: string
      required:
        - task_id
        - status
        - payroll_status_id
      title: CreatePayrollTaskResponse[PayrunStatus]
      type: object
    PayrunStatus:
      description: Payrun status
      enum:
        - DRAFT
        - PROCESSING
        - APPROVED
        - PAID
        - CANCELLED
      title: PayrunStatus
      type: string
  securitySchemes:
    BearerToken:
      bearerFormat: JWT
      description: Get token from Auth0 and paste it here
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.