---
title: "Create a cancellation flow"
method: POST
path: "/vendor/cancellation-flows/flow"
tags: ["Cancellation Flows"]
---

# Create a cancellation flow

`POST /vendor/cancellation-flows/flow`

## Request

- Base URL: `https://smartrr-dev.local.com`
- URL: `https://smartrr-dev.local.com/vendor/cancellation-flows/flow`
- Auth: API key in header `x-smartrr-access-token`

Requires SUBSCRIPTION read and write access. The server generates the flow UUID.

## Request body

- CancellationFlowWrite: A cancellation flow's writable fields, used to create or fully replace one. The flow's uuid is never part of this payload — it's server-generated on create, and comes from the path on update.
  - `label` string, required
  - `order` integer, required
  - `state` 'active' | 'inactive', required
  - `condition` union, required
    - CancellationFlowConditionGroup
      - `type` 'and' | 'or', required
      - `conditions` CancellationFlowCondition[], required
    - CancellationFlowNumericCondition
      - `type` 'orderCount' | 'subscriptionValue' | 'subscriptionTotalQuantity' | 'lifetimeValue' | 'creditBalance' | 'loyaltyTier' | 'distanceToNextLoyaltyTier', required
      - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq', required
      - `value` number, required
    - CancellationFlowProductCondition
      - `type` 'product', required
      - `operator` 'is' | 'not', required
      - `value` string, uuid, required
    - CancellationFlowShippingIntervalCondition
      - `type` 'shippingInterval', required
      - `operator` 'is' | 'not', required
      - `value` CancellationFlowInterval, required
        - `years` integer
        - `months` integer
        - `weeks` integer
        - `days` integer
        - `hours` integer
        - `minutes` integer
        - `seconds` integer
    - CancellationFlowCreationDateCondition
      - `type` 'subscriptionCreationDate', required
      - `operator` 'gt' | 'lt' | 'eq', required
      - `value` string, date-time, required
    - union
      - object
        - `type` 'subscriptionNextBillingDate', required
        - `operator` 'gt' | 'lt' | 'eq', required
        - `value` string, date-time, required
      - object
        - `type` 'subscriptionNextBillingDate', required
        - `operator` 'within', required
        - `interval` CancellationFlowInterval, required
          - `years` integer
          - `months` integer
          - `weeks` integer
          - `days` integer
          - `hours` integer
          - `minutes` integer
          - `seconds` integer
    - CancellationFlowSubscriptionStateCondition
      - `type` 'subscriptionState', required
      - `value` 'active' | 'paused', required
    - CancellationFlowBooleanCondition
      - `type` 'prepaid' | 'prepaidRenewing', required
      - `operator` 'is' | 'not', required
  - `reasons` CancellationFlowReason[], required
    - `uuid` string, uuid, required
    - `label` string, required

## Response `201`

The created cancellation flow.

- CancellationFlow
  - `uuid` string, uuid, required
  - `label` string, required
  - `order` integer, required
  - `state` 'active' | 'inactive', required
  - `condition` union, required
    - CancellationFlowConditionGroup
      - `type` 'and' | 'or', required
      - `conditions` CancellationFlowCondition[], required
    - CancellationFlowNumericCondition
      - `type` 'orderCount' | 'subscriptionValue' | 'subscriptionTotalQuantity' | 'lifetimeValue' | 'creditBalance' | 'loyaltyTier' | 'distanceToNextLoyaltyTier', required
      - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq', required
      - `value` number, required
    - CancellationFlowProductCondition
      - `type` 'product', required
      - `operator` 'is' | 'not', required
      - `value` string, uuid, required
    - CancellationFlowShippingIntervalCondition
      - `type` 'shippingInterval', required
      - `operator` 'is' | 'not', required
      - `value` CancellationFlowInterval, required
        - `years` integer
        - `months` integer
        - `weeks` integer
        - `days` integer
        - `hours` integer
        - `minutes` integer
        - `seconds` integer
    - CancellationFlowCreationDateCondition
      - `type` 'subscriptionCreationDate', required
      - `operator` 'gt' | 'lt' | 'eq', required
      - `value` string, date-time, required
    - union
      - object
        - `type` 'subscriptionNextBillingDate', required
        - `operator` 'gt' | 'lt' | 'eq', required
        - `value` string, date-time, required
      - object
        - `type` 'subscriptionNextBillingDate', required
        - `operator` 'within', required
        - `interval` CancellationFlowInterval, required
          - `years` integer
          - `months` integer
          - `weeks` integer
          - `days` integer
          - `hours` integer
          - `minutes` integer
          - `seconds` integer
    - CancellationFlowSubscriptionStateCondition
      - `type` 'subscriptionState', required
      - `value` 'active' | 'paused', required
    - CancellationFlowBooleanCondition
      - `type` 'prepaid' | 'prepaidRenewing', required
      - `operator` 'is' | 'not', required
  - `reasons` CancellationFlowReason[], required
    - `uuid` string, uuid, required
    - `label` string, required

## Other responses

- `400`: The payload is invalid, includes a flow uuid, or the access token is missing or invalid.
- `401`: The access token does not grant the required scope.
- `422`: The payload is well-formed but requests an active flow that isn't sufficiently populated to be activated (too few/many conditions or reasons).

## Changes

- **2026-10-23** `e0f19b14bb6d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smartrr/apis/smartrr-api/changes/vendor/cancellation-flows/flow/post.md)

---

[API](https://skmtc.dev/smartrr/apis/smartrr-api.md) - [All operations](https://skmtc.dev/smartrr/apis/smartrr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartrr/apis/smartrr-api/revisions/1039006caa74?raw)