---
title: "Unlock a Mission (Spend Currency)"
method: PATCH
path: "/missions/objective/{objectiveId}/player/{playerId}/unlock"
tags: ["Missions"]
---

# Unlock a Mission (Spend Currency)

`PATCH /missions/objective/{objectiveId}/player/{playerId}/unlock`

## Request

- Base URL: `https://opti-ls-api-us.optimove.net/api`
- URL: `https://opti-ls-api-us.optimove.net/api/missions/objective/{objectiveId}/player/{playerId}/unlock`
- Auth: none declared

Some missions are locked behind an unlock cost. Call this when the player taps "Unlock". The required currency is deducted and the mission is activated so progress can begin.

After a successful unlock, re-fetch `GET /player-rewards/brand/{brandId}/player/{playerId}` so the player's balance reflects the deduction.

## Path parameters

- `objectiveId` string, uuid, required
- `playerId` string, required

## Response `200`

The updated mission record.

- MissionItem
  - `objective` Objective
    - `id` string, uuid: UUID of the objective. Use as `objectiveId` in unlock/claim calls.
    - `name` string: Title shown to the player.
    - `description` string, nullable: Optional longer description.
    - `type` 'task' | 'mission': `task` (standalone) or `mission` (part of a mission group).
    - `goal` integer: Target value the player must reach (e.g. 5 purchases).
    - `icon` string, nullable: URL to the mission icon. Validate it is an `https` URL from a trusted host before using in `src`/`href`.
    - `status` 'active' | 'draft' | 'archived' | 'deleted': Lifecycle of the objective definition. Only render `active`.
    - `isRepeatable` boolean: Whether the mission can be completed more than once.
    - `repeatLimit` integer, nullable: Maximum number of times the mission can be repeated. `null` = unlimited.
    - `cooldownPeriodSeconds` integer, nullable: Seconds the player must wait between repeats. `null` = no cooldown.
    - `unlockCurrencyId` string, uuid, nullable: UUID of the currency required to unlock. `null` if no unlock cost.
    - `unlockAmount` integer, nullable: Amount of that currency required to unlock. `null` if no unlock cost.
  - `mission` Mission, nullable: Player's progress record. `null` when the player has never started this objective (render as "Not started").
    - `status` 'active' | 'completed' | 'claimed' | 'locked' | 'failed': Player's current state for this mission. `active` show progress bar; `completed` show Claim button; `claimed` show completion state; `locked` show Unlock button with cost; `failed` show failed state.
    - `progress` integer: How far the player has gotten toward `objective.goal`.
    - `objectiveId` string, uuid: Links back to the parent objective.
    - `playerId` string
    - `repeatCount` integer: How many times the player has already completed and claimed this repeatable mission.
    - `lastRepeated` string, date-time, nullable: ISO 8601 timestamp of the last completion. Use with `cooldownPeriodSeconds` to show next-available time.
    - `version` integer: Internal optimistic-lock counter. Not for display.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `rewards` MissionRewardRef[]
    - `rewardTypeId` string, uuid: UUID of the reward type. Look up name and icon from the rewards catalog using this value.
    - `amount` integer: Quantity of the reward granted on completion.
    - `repeatable` boolean: Whether the reward is granted on every repeat of a repeatable mission, or only on first claim.

## Other responses

- `400`: Invalid request body or parameters.
- `404`: Resource not found (brand, player, mission, leaderboard, etc.).

---

[API](https://skmtc.dev/optimove/apis/optimove-loyalty-system-api.md) - [All operations](https://skmtc.dev/optimove/apis/optimove-loyalty-system-api/llms.txt) - [OpenAPI document](https://skmtc.dev/optimove/apis/optimove-loyalty-system-api/revisions/f174877a5fb7?raw)