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

# Update Collection Status

Updates the status of a collection. This is typically called when your payment provider sends webhook notifications about payment status changes.

## Path Parameters

<ParamField path="id" type="string" required>
  Collection ID
</ParamField>

## Request Body

<ParamField body="status" type="string" required>
  New status. Valid values:

  * `pending`: Payment is pending
  * `completed`: Payment was successful
  * `expired`: Collection has expired
  * `overdue`: Payment is overdue
  * `cancelled`: Collection was cancelled
</ParamField>

## Status Transition Rules

* Once a collection is `completed`, `expired`, `cancelled`, or `overdue`, it cannot be changed to another status
* You cannot set a collection to `pending` if it's already `pending`
* When status changes to a terminal state (completed, expired, cancelled, overdue), any active follow-ups are automatically stopped

## Example Request

```json theme={null}
{
  "status": "completed"
}
```

## Response

<ResponseField name="status" type="string">
  Response status ("success")
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  Full collection object with updated status
</ResponseField>

<ResponseField name="data.status" type="string">
  Updated status
</ResponseField>

<ResponseField name="data.completedAt" type="string">
  ISO 8601 timestamp (set when status is "completed")
</ResponseField>

<ResponseField name="data.events" type="array">
  Updated events array including new status change event
</ResponseField>

## Example Response

```json theme={null}
{
  "status": "success",
  "message": "Collection status updated successfully",
  "data": {
    "id": "pay_9fmz6170pzaih14pmyl0a49o1l",
    "type": "integrated",
    "contact": {
      "id": "contact_gj7iyx04gs7hticrite6m6qdhc",
      "firstName": "Amina",
      "lastName": "Lawal",
      "phone": "+2348012345678",
      "email": "amina@example.com"
    },
    "reference": "PSK_txn_8a7f34",
    "amount": {
      "value": 45000,
      "currency": "NGN"
    },
    "status": "completed",
    "expiresIn": 1440,
    "payable": {
      "enabled": true,
      "methods": ["payment_link", "virtual_account"],
      "options": []
    },
    "followUp": {
      "enabled": true,
      "startAfter": 20,
      "cadence": "every_10m",
      "channels": ["whatsapp", "sms"],
      "tone": "gentle"
    },
    "metadata": [
      {
        "name": "Standard Membership",
        "amount": {
          "value": 15000,
          "currency": "NGN"
        },
        "description": "January plan renewal",
        "quantity": 1
      }
    ],
    "events": [
      {
        "id": "evt_xxx",
        "type": "collection.created",
        "timestamp": "2025-11-12T17:46:07.000Z"
      },
      {
        "id": "evt_yyy",
        "type": "collection.successful",
        "timestamp": "2025-11-12T18:30:00.000Z"
      },
      {
        "id": "evt_zzz",
        "type": "followup.stopped",
        "timestamp": "2025-11-12T18:30:00.000Z"
      }
    ],
    "createdAt": "2025-11-12T17:46:07.000Z",
    "updatedAt": "2025-11-12T18:30:00.000Z",
    "completedAt": "2025-11-12T18:30:00.000Z"
  }
}
```

## Notes

* Status updates automatically create events in the collection's event history
* When status changes to a terminal state, follow-up is automatically stopped
* The `followup.stopped` event is added when follow-up is stopped