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

# Atualizar pedido

> Como usar PATCH /api/v1/orders/{externalId}, status suportados e transições válidas.

Use `PATCH /api/v1/orders/{externalId}` quando o status ou dados permitidos de um pedido mudarem.

## Status aceitos

* `pending`
* `paid`
* `refused`
* `refunded`
* `chargedback`

A API normaliza aliases comuns de gateways. Exemplos:

* `approved`, `completed`, `concluido`, `pago` -> `paid`
* `waiting_payment`, `pendente` -> `pending`
* `rejected`, `failed`, `cancelled`, `recusado` -> `refused`
* `refund`, `reembolsado`, `estornado` -> `refunded`
* `chargeback`, `charged_back`, `dispute` -> `chargedback`

## Transições válidas

| De            | Para                                     |
| ------------- | ---------------------------------------- |
| `pending`     | `pending`, `paid`, `refused`, `refunded` |
| `paid`        | `paid`, `refunded`, `chargedback`        |
| `refunded`    | `refunded`, `chargedback`                |
| `refused`     | `refused`                                |
| `chargedback` | `chargedback`                            |

`refused` e `chargedback` são terminais.

## Payload para marcar como pago

```json theme={null}
{
  "status": "paid",
  "paidAt": "2026-05-10T15:40:00Z"
}
```

## Campos permitidos no PATCH

* `status`
* `paidAt`
* `refundedAt`
* `chargedbackAt`
* `isTest`
* `amounts`
* `customer`
* `tracking`
* `trackingExtras`
* `metadata`

Campos de criação como `externalId`, `platform`, `paymentMethod`, `createdAt`, `products` e `fees` não são atualizados por PATCH.

## Exemplo curl

```bash theme={null}
curl -X PATCH "https://app.atriby.com/api/v1/orders/order_001" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_001_paid" \
  -d '{
    "status": "paid",
    "paidAt": "2026-05-10T15:40:00Z"
  }'
```

## Erros

* `ORDER_NOT_FOUND`: pedido não existe no dashboard autenticado.
* `INVALID_STATUS_TRANSITION`: transição de status inválida.
* `VALIDATION_FAILED`: payload inválido.
* `UNAUTHORIZED` ou `TOKEN_REVOKED`: problema no token.