---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/reference/api/@getenginex/sdk-vue/functions/useEnginexMutation.md
---
[Reference](../../../index.md) / [@getenginex/sdk-vue](../index.md) / useEnginexMutation

# useEnginexMutation()

> **useEnginexMutation**<`I`, `R`, `TOnMutateResult`>(`getter`, `overrides?`): `UseMutationReturnType`<`R`, [`EnginexError`](../../sdk/classes/EnginexError.md), `I`, `TOnMutateResult`>

TanStack `useMutation` over the options of an SDK mutation, with the error typed as
`EnginexError`. It takes a **getter** (not the options). On success it invalidates exactly the keys of
`invalidates(input, result)`, **waits for the refetches to finish** and only then calls the app's `onSuccess`
(in `overrides`): `mutateAsync` and `isPending` end up with the data already updated. On error it invalidates
nothing and the app's `onError` receives the `EnginexError`. An app `onSuccess` that throws does not prevent the
invalidation (it has already happened) and moves the mutation to the error state; in that case `error` is the error
it threw, which is **not** necessarily an `EnginexError`.

`overrides` with an `undefined` value are ignored, and the options' `mutationFn` cannot be replaced.
`TOnMutateResult` is the return of `onMutate`, delivered typed to `onSuccess`, `onError` and `onSettled`.

The `Idempotency-Key` is kept **per composable instance**: it survives getter re-runs and
TanStack's `retry`, and is only reused for the same method and the same content after an
ambiguous failure (network, timeout, 5xx, `KEY_IN_USE` or `VALIDATION_ERROR` after a 2xx). Two instances
never share a key. Pass the adjustments in `overrides`: spreading the options loses the SDK call
and, with it, the per-instance attempt. Options without the SDK call (a synthetic mutation) use their own
`mutationFn`. The options' `gcTime` (`0` on mutations with credentials) is kept.

## Type Parameters

### I

`I`

### R

`R`

### TOnMutateResult

`TOnMutateResult` = `unknown`

## Parameters

### getter

() => [`EnginexMutationOptions`](../../sdk/query/interfaces/EnginexMutationOptions.md)<`I`, `R`>

Returns the options of a mutation (`() => m.deposits.createPix()`).

### overrides?

[`EnginexMutationOverrides`](../type-aliases/EnginexMutationOverrides.md)<`I`, `R`, `TOnMutateResult`>

`useMutation` options (`onSuccess`, `onError`, `retry`...); not `mutationFn`.

## Returns

`UseMutationReturnType`<`R`, [`EnginexError`](../../sdk/classes/EnginexError.md), `I`, `TOnMutateResult`>

The `useMutation` result, with `error` typed as `EnginexError`.

## Throws

If called in an app without the `EnginexPlugin`.

## Example

```ts
const m = useEnginexMutations()
const pix = useEnginexMutation(() => m.deposits.createPix(), {
  onSuccess: (deposit) => router.push(`/deposito/${deposit.id}`),
})
pix.mutate({ amount: 5000 })
```
