> ## 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.

# Cancel Payrun

> Cancel a DRAFT supplementary pay run.

Its pay items are deleted (kept for audit), its payslips deleted and its status set to
CANCELLED; its payment date is free for a new run. A MAIN run cannot be cancelled (409
`INVALID_TRANSITION`, `params.reason` `NOT_SUPPLEMENTARY`), nor a run that is approved or being
calculated (409 `INVALID_TRANSITION`, `params.reason` `NOT_DRAFT`). A supplementary run that
pays employees' salary and statutory pay for the period (they were moved into it, or it
calculated them after the MAIN run was approved without their salary) is refused until they are
moved to another draft run: back to the MAIN run while it is a draft, to another supplementary
run once it is approved.

Alternatively, name exactly those employees in `drop_standing_pay_for`, for instance
for a supplementary run whose payment date has passed. Their salary and statutory pay
then leaves this run, which does not pay it: the next run of the period that
calculates them pays it (the MAIN run while it is a draft, otherwise the first
supplementary run that calculates them). Drop it only to pay it in a later period, for
instance as a back-pay item; to pay it in this one, move the employees first. The
response lists in `unpaid_standing_pay_for` those whose pay no run will now pay: once the
MAIN run is approved, every named employee except those holding pay items in another draft
run of the period, which pays it when calculated again; while it is a draft, those it does not
cover (in positive pay, employees holding no pay items in it). In net change it leaves
out an employee who started in the period, has no payment for it approved and no pay
items in another run of it: the next period's MAIN run pays the period for them
unasked. Their payslips in the period's other draft
runs are deleted with the cancel, so calculate those runs again before approving them;
the cancel is refused (409 `RESULT_NOT_CALCULATED`, `params.reason`
`OTHER_RUN_CALCULATING`) while one of those runs is being calculated for them. Any
other set of employees, including naming someone when the run holds nobody's salary or
statutory pay, is refused (409). The body is optional; without it nobody is named.



## OpenAPI

````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/payruns/{payrun_id}/cancel
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}/cancel:
    post:
      tags:
        - Great Britain
        - Pay Runs
      summary: Cancel Payrun
      description: >-
        Cancel a DRAFT supplementary pay run.


        Its pay items are deleted (kept for audit), its payslips deleted and its
        status set to

        CANCELLED; its payment date is free for a new run. A MAIN run cannot be
        cancelled (409

        `INVALID_TRANSITION`, `params.reason` `NOT_SUPPLEMENTARY`), nor a run
        that is approved or being

        calculated (409 `INVALID_TRANSITION`, `params.reason` `NOT_DRAFT`). A
        supplementary run that

        pays employees' salary and statutory pay for the period (they were moved
        into it, or it

        calculated them after the MAIN run was approved without their salary) is
        refused until they are

        moved to another draft run: back to the MAIN run while it is a draft, to
        another supplementary

        run once it is approved.


        Alternatively, name exactly those employees in `drop_standing_pay_for`,
        for instance

        for a supplementary run whose payment date has passed. Their salary and
        statutory pay

        then leaves this run, which does not pay it: the next run of the period
        that

        calculates them pays it (the MAIN run while it is a draft, otherwise the
        first

        supplementary run that calculates them). Drop it only to pay it in a
        later period, for

        instance as a back-pay item; to pay it in this one, move the employees
        first. The

        response lists in `unpaid_standing_pay_for` those whose pay no run will
        now pay: once the

        MAIN run is approved, every named employee except those holding pay
        items in another draft

        run of the period, which pays it when calculated again; while it is a
        draft, those it does not

        cover (in positive pay, employees holding no pay items in it). In net
        change it leaves

        out an employee who started in the period, has no payment for it
        approved and no pay

        items in another run of it: the next period's MAIN run pays the period
        for them

        unasked. Their payslips in the period's other draft

        runs are deleted with the cancel, so calculate those runs again before
        approving them;

        the cancel is refused (409 `RESULT_NOT_CALCULATED`, `params.reason`

        `OTHER_RUN_CALCULATING`) while one of those runs is being calculated for
        them. Any

        other set of employees, including naming someone when the run holds
        nobody's salary or

        statutory pay, is refused (409). The body is optional; without it nobody
        is named.
      operationId: >-
        cancel_payrun_gb_organizations__organization_id__payruns__payrun_id__cancel_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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayrunCancelRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrunCancelResponse'
          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:
                INVALID_TRANSITION:
                  summary: >-
                    Raised when an operation for SUPPLEMENTARY runs only, such
                    as cancel, names a MAIN run.
                  value:
                    errors:
                      - code: INVALID_TRANSITION
                        message: >-
                          Raised when an operation for SUPPLEMENTARY runs only,
                          such as cancel, names a MAIN run.
                        params:
                          allowed:
                            - SUPPLEMENTARY
                          from: MAIN
                          reason: NOT_SUPPLEMENTARY
                          run_id: run_01j0000000e008000000000001
                INVALID_TRANSITION (NOT_DRAFT):
                  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
                RESULT_NOT_CALCULATED:
                  summary: >-
                    Raised when a supplementary run is cancelled naming
                    employees in `drop_standing_pay_for` while another run of
                    its pay calendar and pay group is being calculated for them.
                  value:
                    errors:
                      - code: RESULT_NOT_CALCULATED
                        message: >-
                          Raised when a supplementary run is cancelled naming
                          employees in `drop_standing_pay_for` while another run
                          of its pay calendar and pay group is being calculated
                          for them.
                RUN_HOLDS_STANDING_PAY:
                  summary: >-
                    Raised when a supplementary run is cancelled and the
                    employees named in `drop_standing_pay_for` are not exactly
                    those whose standing or valued pay elements it holds: an
                    employee moved in from the main run, or one it calculated
                    after the main run was approved holding none of their
                    standing pay.
                  value:
                    errors:
                      - code: RUN_HOLDS_STANDING_PAY
                        message: >-
                          Raised when a supplementary run is cancelled and the
                          employees named in `drop_standing_pay_for` are not
                          exactly those whose standing or valued pay elements it
                          holds: an employee moved in from the main run, or one
                          it calculated after the main run was approved holding
                          none of their standing pay.
              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
                            - RUN_HOLDS_STANDING_PAY
                            - RESULT_NOT_CALCULATED
                          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 an operation for SUPPLEMENTARY
            runs only, such as cancel, names a MAIN run.

            - `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.

            - `RUN_HOLDS_STANDING_PAY`: Raised when a supplementary run is
            cancelled and the employees named in `drop_standing_pay_for` are not
            exactly those whose standing or valued pay elements it holds: an
            employee moved in from the main run, or one it calculated after the
            main run was approved holding none of their standing pay.

            - `RESULT_NOT_CALCULATED`: Raised when a supplementary run is
            cancelled naming employees in `drop_standing_pay_for` while another
            run of its pay calendar and pay group is being calculated for them.
        '422':
          content:
            application/json:
              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:
                            - 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.
      security:
        - BearerToken: []
components:
  schemas:
    PayrunCancelRequest:
      additionalProperties: false
      properties:
        drop_standing_pay_for:
          description: >-
            Exactly the employees whose salary and statutory pay for the period
            the run holds, or the cancel is refused; omit (or leave empty) when
            it holds nobody's. Naming them moves that pay out of this run, which
            does not pay it: the next run of the period that calculates them
            pays it (the MAIN run while it is a draft, otherwise the first
            supplementary run that calculates them). Drop it only to pay it in a
            later period: the response lists in `unpaid_standing_pay_for` those
            whose pay no run will now pay. To pay it in this period, move them
            to another draft run first.
          items:
            type: string
          title: Drop Standing Pay For
          type: array
      title: PayrunCancelRequest
      type: object
    PayrunCancelResponse:
      additionalProperties: false
      properties:
        contractual_payday:
          description: 'The pay calendar''s pay date: the day the period''s pay is due.'
          format: date
          title: Contractual Payday
          type: string
        external_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: External Ref
        id:
          title: Id
          type: string
        pay_calendar_id:
          title: Pay Calendar Id
          type: string
        pay_group_id:
          title: Pay Group Id
          type: string
        payment_date:
          description: >-
            The day the run's BACS payment reaches employees' accounts: a
            SUPPLEMENTARY run's own date, the pay calendar's deposit date for a
            MAIN run (which moves off `contractual_payday` when that is not a
            banking day).
          format: date
          title: Payment Date
          type: string
        payroll_status_id:
          title: Payroll Status Id
          type: string
        reported_payment_date:
          description: >-
            The payment date the run reports to HMRC on the FPS:
            `contractual_payday` for a MAIN run, `payment_date` for a
            SUPPLEMENTARY run.
          format: date
          title: Reported Payment Date
          type: string
        run_type:
          $ref: '#/components/schemas/PayRunType'
        status:
          $ref: '#/components/schemas/PayrunStatus'
        unpaid_standing_pay_for:
          description: >-
            Those named in `drop_standing_pay_for` whose salary and statutory
            pay for the period no run will now pay: once the MAIN run is
            approved, all of them except those holding pay items in another
            draft run of the period, which pays it when calculated again; while
            it is a draft, those it does not cover (in positive pay, employees
            holding no pay items in it). Pay it in a later period, for instance
            as a back-pay item. Not listed, in net change: an employee who
            started in the period, has no payment for it approved and no pay
            items in another run of it. The next period's MAIN run pays the
            period for them unasked, so back pay would pay it twice. Empty when
            nobody was named or the MAIN run pays every named employee.
          items:
            type: string
          title: Unpaid Standing Pay For
          type: array
      required:
        - id
        - payroll_status_id
        - run_type
        - status
        - pay_calendar_id
        - pay_group_id
        - payment_date
        - contractual_payday
        - reported_payment_date
        - external_ref
      title: PayrunCancelResponse
      type: object
    PayRunType:
      description: >-
        Kind of pay run: the period's main run, or a supplementary run in the
        same period
      enum:
        - MAIN
        - SUPPLEMENTARY
      title: PayRunType
      type: string
    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.