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

# Cancel journey runs

> Cancel journey runs. The request body must include EXACTLY ONE of `cancelation_token` (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped run). Supplying both or neither returns a `400`. A `run_id` that does not match a run for the tenant returns `404`. Cancelation is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left unchanged and its current status is returned.



## OpenAPI

````yaml /openapi-specs/openapi.documented.yml post /journeys/cancel
openapi: 3.0.1
info:
  title: Courier
  description: The Courier REST API for sending and managing notifications across channels.
  version: 0.0.1
servers:
  - url: https://api.courier.com
    description: Production
security: []
paths:
  /journeys/cancel:
    post:
      tags:
        - Journeys
      summary: Cancel journey runs
      description: >-
        Cancel journey runs. The request body must include EXACTLY ONE of
        `cancelation_token` (cancels every run associated with the token) or
        `run_id` (cancels a single tenant-scoped run). Supplying both or neither
        returns a `400`. A `run_id` that does not match a run for the tenant
        returns `404`. Cancelation is idempotent: a run that has already
        finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left
        unchanged and its current status is returned.
      operationId: journeys_cancel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelJourneyRequest'
            examples:
              ByCancelationToken:
                summary: Cancel every run for a cancelation token
                value:
                  cancelation_token: order-1234
              ByRunId:
                summary: Cancel a single run by id
                value:
                  run_id: 1-5f0c3b9a-abcdef0123456789
      responses:
        '202':
          description: Cancelation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelJourneyResponse'
              examples:
                ByCancelationToken:
                  summary: Token branch
                  value:
                    cancelation_token: order-1234
                ByRunId:
                  summary: Run id branch
                  value:
                    run_id: 1-5f0c3b9a-abcdef0123456789
                    status: CANCELED
        '400':
          description: Bad request — both or neither of cancelation_token / run_id supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                Example:
                  value:
                    message: exactly one of cancelation_token or run_id is required
                    type: invalid_request_error
        '404':
          description: A run_id was supplied but no matching run exists for this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                Example:
                  value:
                    message: run not found
                    type: invalid_request_error
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
              examples:
                Example:
                  value:
                    message: Example message text
                    type: invalid_request_error
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Courier from '@trycourier/courier';


            const client = new Courier({
              apiKey: process.env['COURIER_API_KEY'], // This is the default and can be omitted
            });


            const cancelJourneyResponse = await client.journeys.cancel({
            cancelation_token: 'order-1234' });


            console.log(cancelJourneyResponse);
        - lang: Python
          source: |-
            import os
            from courier import Courier

            client = Courier(
                api_key=os.environ.get("COURIER_API_KEY"),  # This is the default and can be omitted
            )
            cancel_journey_response = client.journeys.cancel(
                cancelation_token="order-1234",
            )
            print(cancel_journey_response)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/trycourier/courier-go\"\n\t\"github.com/trycourier/courier-go/option\"\n)\n\nfunc main() {\n\tclient := courier.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{\n\t\tCancelJourneyRequest: courier.CancelJourneyRequestUnionParam{\n\t\t\tOfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{\n\t\t\t\tCancelationToken: \"order-1234\",\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", cancelJourneyResponse)\n}\n"
        - lang: Java
          source: |-
            package com.courier.example;

            import com.courier.client.CourierClient;
            import com.courier.client.okhttp.CourierOkHttpClient;
            import com.courier.models.journeys.CancelJourneyRequest;
            import com.courier.models.journeys.CancelJourneyResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    CourierClient client = CourierOkHttpClient.fromEnv();

                    CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
                        .cancelationToken("order-1234")
                        .build();
                    CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);
                }
            }
        - lang: Ruby
          source: >-
            require "courier"


            courier = Courier::Client.new(api_key: "My API Key")


            cancel_journey_response =
            courier.journeys.cancel(cancel_journey_request: {cancelation_token:
            "order-1234"})


            puts(cancel_journey_response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Courier\Client;

            use Courier\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('COURIER_API_KEY') ?: 'My API
            Key');


            try {
              $cancelJourneyResponse = $client->journeys->cancel(
                cancelationToken: 'x', runID: 'x'
              );

              var_dump($cancelJourneyResponse);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: >-
            using System;

            using TryCourier;

            using TryCourier.Models.Journeys;


            CourierClient client = new();


            JourneyCancelParams parameters = new()

            {
                CancelJourneyRequest = new ByCancelationToken("order-1234")
            };


            var cancelJourneyResponse = await
            client.Journeys.Cancel(parameters);


            Console.WriteLine(cancelJourneyResponse);
        - lang: CLI
          source: |-
            courier journeys cancel \
              --api-key 'My API Key' \
              --cancelation-token x \
              --run-id x
components:
  schemas:
    CancelJourneyRequest:
      description: >-
        Request body for `POST /journeys/cancel`. Provide EXACTLY ONE of
        `cancelation_token` (cancels every run associated with the token) or
        `run_id` (cancels a single tenant-scoped run).
      oneOf:
        - type: object
          title: By cancelation token
          properties:
            cancelation_token:
              type: string
              minLength: 1
          required:
            - cancelation_token
          additionalProperties: false
        - type: object
          title: By run id
          properties:
            run_id:
              type: string
              minLength: 1
          required:
            - run_id
          additionalProperties: false
    CancelJourneyResponse:
      description: >-
        `202 Accepted` body for `POST /journeys/cancel`, returning the submitted
        identifier. When called with `cancelation_token`, returns `{
        cancelation_token }`; when called with `run_id`, returns `{ run_id,
        status }`.
      oneOf:
        - type: object
          title: Token branch
          properties:
            cancelation_token:
              type: string
          required:
            - cancelation_token
        - type: object
          title: Run id branch
          properties:
            run_id:
              type: string
            status:
              type: string
              description: >-
                The run's resulting status. `CANCELED` when the run was active
                and has been canceled; `PROCESSED` or `ERROR` when the run had
                already finished and was left unchanged; `CANCELED` for an
                already-canceled run.
          required:
            - run_id
            - status
    BadRequest:
      title: BadRequest
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    NotFound:
      title: NotFound
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    UnprocessableEntity:
      title: UnprocessableEntity
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    BaseError:
      title: BaseError
      type: object
      properties:
        message:
          type: string
          description: A message describing the error that occurred.
      required:
        - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````