---
title: "Update a match's lifecycle status"
method: PATCH
path: "/game/matches/{matchId}/status"
tags: ["Game: Matches"]
---

# Update a match's lifecycle status

`PATCH /game/matches/{matchId}/status`

Transitions a match between lifecycle states (validated against allowed transitions). Requires the game.lifecycle:read-write permission. Supports an optional `Idempotency-Key` request header that deduplicates concurrent duplicate submissions: while one request is in flight, a second request with the same key and body resolves to the same outcome, and the same key with a different body returns 409 error_idempotency_key_conflict. The idempotency identity is scoped per match and per target status. Note that this endpoint validates the live match state first, so a sequential retry sent after the transition has already succeeded returns the normal transition error (error_match_not_in_valid_state) - the live state no longer permits the transition - rather than a replayed success.

## Path parameters

- `matchId` string, required — Match ID.

## Request body

- GameStatusUpdateBody — Request body for updating a match's lifecycle status.
  - `status` string, required — Target status. Allowed transitions: READY -> IN_PROGRESS, IN_PROGRESS -> COMPLETED|CANCELLED, ACCEPTED -> CANCELLED. COMPLETED is not accepted directly (matches complete automatically once scores are confirmed).

## Response `200`

The match status was transitioned successfully.

- GameStatusUpdateResponse — Result of a successful match status transition.
  - `success` true, required
  - `matchId` string, required — ID of the updated match.
  - `previousStatus` string, required — Match status before the transition.
  - `newStatus` string, required — Match status after the transition.
  - `timestamp` string, required — Server response time (ISO 8601).

## Other responses

- `400` — Bad request (invalid body, cursor, limit, or date).
- `401` — Missing or invalid API key.
- `403` — API key lacks the required permission.
- `404` — Resource not found.
- `409` — Conflict.

---

[API](https://skmtc.net/teambattles/apis/teambattles-api.md) · [All operations](https://skmtc.net/teambattles/apis/teambattles-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/teambattles/teambattles-api/versions/2ffe8fb53b7d/schema)