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

# Create dispute case transition

> Transition a dispute case to another state or initiate a chargeback against the dispute case.

<div className="mb-4 flex items-center gap-2"><span className="rounded-lg font-bold px-1.5 py-0.5 text-sm leading-5 bg-blue-400/20 text-blue-700 dark:text-blue-400">POST</span><span className="flex items-center gap-0.5 font-mono text-sm"><span className="text-gray-400">/</span><span className="font-medium text-gray-800 dark:text-white">{"cases"}</span><span className="text-gray-400">/</span><span className="font-medium text-gray-800 dark:text-white">{"{token}"}</span><span className="text-gray-400">/</span><span className="font-medium text-gray-800 dark:text-white">{"transitions"}</span></span></div>

Transition a dispute case to another state or initiate a chargeback against the dispute case.

A dispute case transition is an event that changes the state of a dispute case and triggers other related events. The new state of the dispute case and which related events are triggered is determined by the action defined in the dispute case transition.

<h2 id="_url_path_parameters_4">
  URL path parameters
</h2>

| Fields | Description |
| - | - |
| token<br />string<br />Required | The token of the dispute case associated with the transition you want to create.<br />**Allowable Values:**<br />36 char max<br />Send a `GET` request to `/cases` to retrieve dispute case tokens. |

<h2 id="_body_field_details_4">
  Body field details
</h2>

| Fields | Description |
| - | - |
| token<br />string<br />Optional | The unique identifier of the dispute case transition. If you do not include a token, the system generates a token automatically.<br />**Allowable Values:**<br />36 char max |
| action<br />string<br />Required | The action taken on the dispute case.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_dispute_case_transitions">Dispute case transitions</a>. |
| reason\_code<br />string<br />Required | Identifies the standardized reason for the transition.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_the_transition_reason_code_field">The transition reason\_code field</a> table. |
| created\_by<br />string<br />Required | The user ID or name of the user who created the transition.<br />**Allowable Values:**<br />255 char max |
| assignee<br />string<br />Optional | The user ID or name of the user assigned to the dispute case.<br />**Allowable Values:**<br />255 char max |
| memo<br />string<br />Optional | Additional notes about the transition.<br />**Allowable Values:**<br />16777215 char max |
| transition\_details<br />object<br />Required | An object containing the transition details.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_the_transition_details_object">The transition\_details object</a>. |

<h2 id="_the_transition_details_object">
  The transition\_details object
</h2>

| Fields | Description |
| - | - |
| chargeback\_details<br />object<br />Required | An object containing the chargeback details.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_the_chargeback_details_object">The chargeback\_details object</a>. |

<h2 id="_the_chargeback_details_object">
  The chargeback\_details object
</h2>

| Fields | Description |
| - | - |
| attached\_contents<br />string<br />Required | List of content tokens that should be submitted to the network when initiating a chargeback. The content tokens should be associated to the case. For more information about uploading case documents, see <a href="/docs/core-api/disputes-visa/create-case-content">Create dispute case content</a>.<br />**Allowable Values:**<br />A list of valid UUID tokens. |

<h2 id="_dispute_case_transitions">
  Dispute case transitions
</h2>

Dispute case transitions represent the workflow during the creation, information gathering, and submission processes of a dispute case. The dispute case transition actions and resulting states are described below.

| Action | Reason Code | Resulting State | Description |
| - | - | - | - |
| CREATE | N/A | `OPEN`, `OPEN_WITH_ACTION_REQUIRED` | Creates a new dispute case. A default action when a `POST` request is sent to the `/cases` endpoint. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user.<br />For programs that are enabled for Regulation E, this action and reason code returns an error for a Regulation E dispute and sets `provisionalCreditGranted` to `true`. |
| RE\_OPEN | N/A | `OPEN` | Reopens a dispute case to get additional information or documents. Dispute case state changes to `OPEN`. |
| CHARGEBACK\_CREDIT | 28 | `CHARGEBACK_INITIATED` | Sends a `POST` request to the `\cases` endpoint with `credit_user` set to `true`. Set `reason_description` as the value of `dispute_reason` and `channel` as `ISSUER_AUTOMATED` when creating the chargeback.<br />Dispute case state changes to `CHARGEBACK_INITIATED` if no additional information is required. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user before the chargeback can be submitted to the network.<br />Only for programs that are not enabled for Regulation E. |
| CHARGEBACK\_NO\_CREDIT | 29 | `CHARGEBACK_INITIATED` | Sends a `POST` request to the `\cases` endpoint with `credit_user` set to `false`. Set `reason_description` as the value of `dispute_reason` and `channel` as `ISSUER_AUTOMATED` when creating the chargeback.<br />Dispute case state changes to `CHARGEBACK_INITIATED` if no additional information is required. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user before the chargeback can be submitted to the network.<br />Only for programs that are not enabled for Regulation E. For programs that are enabled for Regulation E, this action and reason code return an error for a Regulation E dispute. |
| CHARGEBACK\_SUBMIT | 51 | `CHARGEBACK_INITIATED` | Submitting dispute to the network. This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error. |
| REVIEW | N/A | `READY` | Dispute case is ready to review. Dispute case state changes to `READY`. |
| ASSIGN | N/A | No change | Assigns a dispute case to a user. An `assignee` value is required. Does not change dispute case state. |
| KYC\_OVERRIDE | N/A | `CLOSED` | Documents are verified and the case is being closed. |
| CLOSE | 41 | `CLOSED` | Closes the dispute case.<br />The case was won. Dispute case state changes to `CLOSED`. For all types of dispute cases, this action cannot be triggered until `dispute_state` is in a `CASE_WON` state. |
| CLOSE | 42 | `CLOSED`/`PENDING_CLOSED` | Closes the dispute case. The case was lost. For non-Regulation E cases, this results in the `CLOSED` state. For Regulation E cases, this results in the `PENDING_CLOSED` state. |
| CLOSE | 45 | `CLOSED` | Closes the dispute case. Dispute case state changes to `CLOSED`. This reason code indicates that the case will be closed and written off using funds from the program account. |
| DOCUMENTS\_DELETED | N/A | No change | Invalid documents were uploaded, documents are not in a readable format or quality, or documents are corrupted and not human readable. |
| REINSTATE\_USER | N/A | `CLOSED` | Failed to reinstate the user. |
| REINSTATE\_BUSINESS | N/A | `CLOSED` | Failed to reinstate the business. |
| WITHDRAW\_AND\_CLOSE | 40 | `CLOSED` | No further action is needed, closing the case by withdrawing.<br />This action can only be taken from the `OPEN` or `OPEN_WITH_ACTION_REQUIRED` state and when provisional credit has not been granted. |
| WRITE\_OFF | N/A | No change | Written off either by user or program. |
| GRANT\_CREDIT | N/A | No change | Granting provisional credit. |
| REVERT\_CREDIT | N/A | No change | Reverting provisional credit. |
| CHANGE\_CASE\_TYPE | N/A | No change | Change case from `DISPUTE` type to the `LEGACY_DISPUTE` type. |

<h2 id="_the_transition_reason_code_field">
  The transition reason\_code field
</h2>

The transition reason code identifies the standardized reason for the transition.

| Reason Code | Description | Related Actions |
| - | - | - |
| 00 | The dispute case was created. | `CREATE` |
| 01 | The dispute case was created, but needs additional verification actions. | `CREATE` |
| 05 | The dispute case is under review. | `REVIEW` |
| 14 | The Marqeta platform updated the dispute case. | `CLOSE`, `NON_CHARGEBACK_CREDIT` |
| 15 | An update was initiated by the issuer. | `REINSTATE_USER`, `REINSTATE_BUSINESS` |
| 18 | The user or business status was changed to `ACTIVE` because information was properly validated and confirmed. | `REINSTATE_USER`, `REINSTATE_BUSINESS` |
| 19 | The user or business status was changed to `ACTIVE` because account activity was properly validated and confirmed. | `REINSTATE_USER`, `REINSTATE_BUSINESS` |
| 22 | The dispute case was assigned to a user. | `ASSIGN` |
| 23 | The dispute case was reopened. | `RE_OPEN` |
| 24 | The dispute case was reopened to gather more information. | `RE_OPEN`, `DOCUMENTS_DELETED` |
| 25 | The documents were verified and the dispute case is being closed. | `CLOSE`, `KYC_OVERRIDE`, `REINSTATE_USER`, `REINSTATE_BUSINESS` |
| 26 | The customer closed the dispute case. | `CLOSE` |
| 27 | The dispute is for a smaller amount and no chargeback is needed. | `NON_CHARGEBACK_CREDIT` |
| 28 | A chargeback was created and the cardholder was credited.<br />Only for programs that are not enabled for Regulation E. | `CHARGEBACK_CREDIT` |
| 29 | A chargeback was created and the cardholder was not credited.<br />Only for programs that are not enabled for Regulation E. | `CHARGEBACK_NO_CREDIT` |
| 30 | The dispute case was closed automatically due to inactivity. | `CLOSE`, `WITHDRAW_AND_CLOSE` |
| 31 | Invalid documents were uploaded. | `DOCUMENTS_DELETED` |
| 32 | Documents were uploaded that are unreadable because of incorrect format or poor quality. | `DOCUMENTS_DELETED` |
| 33 | Corrupted documents were uploaded. | `DOCUMENTS_DELETED` |
| 34 | The chargeback failed.<br />Only for programs that are not enabled for Regulation E. | `CHARGEBACK_CREDIT`, `CHARGEBACK_NO_CREDIT` |
| 35 | The chargeback failed at the card network.<br />Only for programs that are not enabled for Regulation E. | `CHARGEBACK_CREDIT`, `CHARGEBACK_NO_CREDIT`, `CLOSE` |
| 36 | KYC override failed. | `KYC_OVERRIDE` |
| 37 | User reinstatement failed. | `REINSTATE_USER` |
| 38 | Business reinstatement failed. | `REINSTATE_BUSINESS` |
| 39 | Associated transaction selection is required to ready this dispute case. | |
| 40 | No further action is needed. Closing the dispute case by withdrawing.<br />Only used when the provisional credit has not been granted in the `OPEN` and `OPEN_WITH_ACTION_REQUIRED` states. For Regulation E and non-Regulation E cases, this results in the `CLOSED` state and the chargeback is `WITHDRAWN`. | `WITHDRAW_AND_CLOSE` |
| 41 | The dispute case was won, accepted with favorable results, for all types of dispute cases.<br />This action cannot trigger until the `dispute_state` is `CASE_WON`. | `CLOSE` |
| 42 | The dispute case was lost, accepted with unfavorable results.<br />For non-Regulation E dispute cases, this results in the `CLOSED` state. For Regulation E dispute cases, this results in `PENDING_CLOSED`. | `CLOSE` |
| 43 | The dispute case was rejected by the network. | `CLOSE` |
| 44 | The dispute case was written off by the issuer. | `WRITE_OFF`, `CLOSE` |
| 45 | The dispute case was closed and written off by the program using funds from the program account. | `WRITE_OFF`, `CLOSE` |
| 46 | Provisional credit has been granted. | `GRANT_CREDIT` |
| 47 | Provisional credit has been reverted. | `REVERT_CREDIT` |
| 48 | A failure occurred when attempting to transition to the `READY` state. | No change |
| 49 | The dispute case was reported to the network as `FRAUD`. | `WITHDRAW_AND_CLOSE` |
| 50 | The dispute case was changed from `DISPUTE` type to `LEGACY_DISPUTE` type. | `CHANGE_CASE_TYPE` |
| 51 | Submitting dispute to the network.<br />This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error. | `CHARGEBACK_SUBMIT` |
| 52 | Provisional credit is required for a Regulation E dispute case. | |
| 53 | Awaiting milestone. | |

<h2 id="_dispute_transition_response">
  Dispute transition response
</h2>

| Fields | Description |
| - | - |
| case\_token<br />string<br />Returned | The unique identifier of the dispute case.<br />**Allowable Values:**<br />36 char max |
| token<br />string<br />Returned | The unique identifier of the dispute case transition. If you did not include a token, the system generates a token automatically.<br />**Allowable Values:**<br />36 char max |
| action<br />string<br />Returned | The action taken on the dispute case.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_dispute_case_transitions">Dispute case transitions</a>. |
| reason\_code<br />string<br />Returned | Identifies the standardized reason for the transition.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_the_transition_reason_code_field">The transition reason\_code field</a> table. |
| reason\_description<br />string<br />Returned | A descriptive reason for the transition.<br />**Allowable Values:**<br />36 char max |
| created\_by<br />string<br />Returned | The user ID or name of the user who created the transition.<br />**Allowable Values:**<br />36 char max |
| from\_state<br />string<br />Returned | The state of the dispute case before the case transition was created.<br />**Allowable Values:**<br />`OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED` |
| state<br />string<br />Returned | The resulting state of the dispute case after the transition was created.<br />**Allowable Values:**<br />`OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED` |
| assignee<br />string<br />Returned | The user ID or name of the user assigned to the dispute case.<br />**Allowable Values:**<br />255 char max |
| memo<br />string<br />Returned | Additional notes about the transition.<br />**Allowable Values:**<br />512 char max |
| failure\_reason<br />string<br />Returned | If an error occurred while attempting to transition the dispute case, this field provides a brief description of the failure.<br />**Allowable Values:**<br />512 char max |
| transition\_details<br />object<br />Returned | An object containing the transition details.<br />**Allowable Values:**<br />See <a href="/docs/core-api/disputes-visa/create-case-transition#_the_transition_details_object">The transition\_details object</a>. |

<h2 id="_sample_request_body_chargeback_credit">
  Sample request body (CHARGEBACK\_CREDIT)
</h2>

This sample is only for programs that are not enabled for Regulation E.

```json JSON lines wrap theme={null}
{
  "token": "dispute_case_token",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "28",
  "created_by": "user_name",
  "assignee": "assignee_name",
  "memo": "Text about this dispute",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}
```

<h2 id="_sample_response_body_chargeback_credit">
  Sample response body (CHARGEBACK\_CREDIT)
</h2>

This sample is only for programs that are not enabled for Regulation E.

```json JSON lines wrap theme={null}
{
  "case_token": "my_case_id",
  "token": "my_casetransition_id",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "28",
  "reason_description": "Smaller Amount",
  "created_by": "user_name",
  "from_state": "OPEN",
  "state": "CHARGEBACK_INITIATED",
  "assignee": "assignee_name",
  "memo": "Text about this dispute",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}
```

<h2 id="_sample_request_body_chargeback_no_credit">
  Sample request body (CHARGEBACK\_NO\_CREDIT)
</h2>

```json JSON lines wrap theme={null}
{
  "token": "dispute_case_token",
  "action": "CHARGEBACK_NO_CREDIT",
  "reason_code": "29",
  "created_by": "user_name",
  "assignee": "assignee_name",
  "memo": "Initiating chargeback",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}
```

<h2 id="_sample_response_body_chargeback_no_credit">
  Sample response body (CHARGEBACK\_NO\_CREDIT)
</h2>

```json JSON lines wrap theme={null}
{
  "case_token": "my_case_id",
  "token": "my_casetransition_id",
  "action": "CHARGEBACK_N0_CREDIT",
  "reason_code": "29",
  "reason_description": "Smaller Amount",
  "created_by": "user_name",
  "from_state": "OPEN",
  "state": "CHARGEBACK_INITIATED",
  "assignee": "assignee_name",
  "memo": "Initiating chargeback",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}
```

<h2 id="_response_actionreason_code_changes">
  Response action/reason code changes
</h2>

There are some cases where the reason code is changed by the system for either of two reasons:

* An error occurred while processing a transition.
* The dispute case transition moved the case to a state different from the desired state.

| Action | Reason Code | Resulting State | Description |
| - | - | - | - |
| `CHARGEBACK_SUBMIT` | 52 | `OPEN_WITH_ACTION_REQUIRED` | Triggered during an attempt to transition a dispute case with action `CHARGEBACK_SUBMIT` and reason code 51. Occurs when attempting to transition a Regulation E dispute case that has not granted provisional credit. |
| `CLOSE` | 53 | `PENDING_CLOSED` | Triggered during an attempt to transition a dispute case with action `CLOSED` and reason code 42. Occurs for Regulation E cases to indicate that the customer must first notify the cardholder before reverting the credit, as required by Regulation E, and must wait a specified number of days before reverting credit. |

<h2 id="_sample_response_body_actionreason_code_changes">
  Sample response body (ACTION/REASON CODE CHANGES)
</h2>

```json JSON lines wrap theme={null}
{
  "token": "string",
  "case_token": "string"
  "reason_code": "51",
  "reason_description": "Submit case to the card network"
  "created_by": "string",
  "from_state": "READY",
  "state": "CHARGEBACK_INITIATED",
  "action": "CHARGEBACK_SUBMIT",
  "memo": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": ["uuid"]
    }
  }
}
```

<h2 id="_transition_failure_response">
  Transition failure response
</h2>

An error occurs when attempting to transition a dispute case using `CHARGEBACK_SUBMIT` when the dispute has no provisional credit granted.

<h3 id="_error_response">
  Error response
</h3>

| Error Code | Error Message | Description |
| - | - | - |
| 400400 | Attempted to close case as case won when the dispute state is not set to CASE\_WON | Triggered when an attempt to close a case as `CASE_WON` without having it be won in the backend lifecycle. |
| 400400 | Cannot write off cases that haven't granted provisional credit | Triggered during an attempt to transition a case with action `CLOSE` and reason code 45. Occurs for Regulation E cases if provisional credit has not been granted. Solution: Close the case using `WITHDRAW_AND_CLOSE`. |
| 400401 | Case is no longer applicable as case lost under RegE | Triggered during an attempt to transition a dispute case with action `CLOSE` and reason code 42. Occurs for Regulation E cases that are past the Regulation E 45-day time limit.<br />Solution: Close the case with reason code 45. |
| 400400 | Invalid Action for Current State | Triggered during `CHARGEBACK_SUBMIT` if the program is not Regulation E enabled. Triggered during `CHARGEBACK_CREDIT` or `CHARGEBACK_NO_CREDIT` when attempting to use this action to transition a REG\_E case. |
| 400400 | Unable to withdraw and close because provisional credit has been granted | Triggered during an attempt to transition a case with `WITHDRAW_AND_CLOSE` when the provisional credit has been granted. |
| 400400 | Waiting for provisional credit to be reversed before the case can be closed | Triggered during an attempt to transition a case with action `CLOSE` and reason code 42. Occurs if the case is in `PENDING_CLOSED` state and the reversal of provisional credit has not occurred.<br />Solution: Wait for the provisional credit to be reversed. |

<h2 id="_sample_response_body_transition_failure_response">
  Sample response body (TRANSITION FAILURE RESPONSE)
</h2>

```json JSON lines wrap theme={null}
{
  "token": "string",
  "case_token": "string"
  "reason_code": "52",
  "reason_description": "Provisional credit required"
  "created_by": "string",
  "from_state": "READY",
  "state": "OPEN_WITH_ACTION_REQUIRED",
  "action": "CHARGEBACK_SUBMIT",
  "memo": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": ["uuid"]
    }
  }
}
```


## Related topics

- [Create dispute case transition](/docs/core-api/disputes-pulse/create-case-transition.md)
- [Disputes (PULSE) Overview](/docs/core-api/disputes-pulse.md)
- [Disputes (Mastercard) Overview](/docs/core-api/disputes-mastercard.md)
- [Disputes (Visa) Overview](/docs/core-api/disputes-visa.md)
- [Create a Dispute](/docs/developer-guides/disputes-sandbox/disputes-sandbox-submit-manage.md)