---
title: "Run scenario"
method: POST
path: "/simulate/entities/{entityId}/scenarios/{scenarioId}"
tags: ["Onboarding Simulator"]
---

# Run scenario

`POST /simulate/entities/{entityId}/scenarios/{scenarioId}`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/simulate/entities/{entityId}/scenarios/{scenarioId}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `string` scopes: `accounts`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/simulate/entities/:entityId/scenarios/:scenarioId/post.ts> (a function with typed inputs; its response is checked against the schema)

**Sandbox only** — not available in Production.

Executes a pre-defined scenario against an entity, triggering the associated state transition or capability change. Use GET /simulate/scenarios to list available scenario IDs.

## Response `200`

Scenario executed successfully

- SimulatorRunScenarioResponse
  - `entity_id` string: The ID of the entity.
  - `scenario_id` string: The ID of the scenario that was run.
  - `scenario_name` string: The name of the scenario that was run.
  - `previous_status` string: The entity status before the scenario ran.
  - `current_status` string: The entity status after the scenario ran.
  - `requirements_due` string[]: Requirement fields applied by the scenario, if any.

## Other responses

- `202`: Scenario execution accepted and in progress
- `401`: Unauthorized
- `404`: Entity or scenario not found
- `502`: Dependency error

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)