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

# Criar pedido

> Cria um pedido para comprar, renovar ou fazer upgrade de um plano.

**type** `string` (default: purchase)

Para que serve o pedido. Valores possíveis: `purchase`, `renew`, `upgrade`.

**plan** `string` *required*

O slug do plano que está sendo comprado, renovado ou para o qual se faz upgrade.

**months** `integer` *required*

Quantos meses comprar: `1`, `3` ou `12`. O plano Economy aceita apenas `1`. Qualquer outro valor
retorna `INVALID_MONTHS`. Um pedido de 3 meses tem 5% de desconto e um pedido de 12 meses tem 15% de desconto sobre o
preço mensal; `price` e `discount` já incluem isso.

**coupon** `string`

Um código de cupom de desconto opcional.

> [!NOTE]
>
> O pedido precisa de dados de cobrança completos: verifique `complete` em [Obter dados de cobrança](https://docs.vertracloud.app/pt-br/api-reference/endpoint/billing/get-billing-details.md).

> [!NOTE]
>
> Um pedido `renew` exige que o plano de destino seja igual ao plano atual da conta; um pedido
> `upgrade` exige que ele seja estritamente maior. Use `type: "purchase"` quando ainda não houver um plano ativo
> desse tipo.

### Resposta

**response** `object`

**Mostrar objeto**

**id** `string`

O ID do pedido.

**code** `string | null`

O código de resgate, quando o pedido foi criado fluxo baseado em código; `null` nos demais casos.

**status** `string`

Sempre `unpaid` logo após a criação.

**plan** `string`

O nome do plano.

**duration** `integer`

Duração em meses.

**discount** `object`

**Mostrar objeto**

**percent** `number | null`

Porcentagem de desconto aplicada, se houver.

**coupon** `string | null`

O código do cupom aplicado, se houver.

**price** `number`

O preço antes do desconto.

**price** `number`

O preço final, depois do desconto.

**expires\_at** `string | null`

Quando o pedido (e a sua cobrança PIX, depois de gerada) expira sem pagamento.

**allowed\_payment\_methods** `string[]`

Os meios de pagamento que o pedido aceita. O plano Economy retorna `["pix"]`; um cupom restrito a
um meio também reduz a lista.

```json Response theme={null}
{
  "response": {
    "id": "order-abc123",
    "code": null,
    "status": "unpaid",
    "plan": "PRO",
    "duration": 1,
    "discount": { "percent": null, "coupon": null, "price": 24.9 },
    "price": 24.9,
    "expires_at": "2026-09-22T12:00:00.000Z",
    "allowed_payment_methods": ["pix"]
  }
}
```

### Respostas de erro

**code** `string`

O código de erro que indica o motivo da falha. Valores possíveis:

* `AUTH_TOKEN_MISSING`, `API_KEY_INVALID`, `SESSION_REVOKED`: o header `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada (`401`).
* `API_KEY_IP_DENIED`, `API_KEY_SCOPE_DENIED`: a chave de API é usada a partir de um IP fora da sua allowlist, ou não tem o escopo que a rota exige (`403`).
* `USER_NOT_FOUND`: o usuário autenticado não foi encontrado.
* `INVALID_PAYLOAD`: o body da requisição falhou na validação.
* `BILLING_DETAILS_INCOMPLETE`: os dados de cobrança não estão completos (nome, endereço e, no Brasil, CPF/CNPJ). Salve-os com [Atualizar dados de cobrança](https://docs.vertracloud.app/pt-br/api-reference/endpoint/billing/update-billing-details.md) e tente de novo.
* `MISSING_PLAN_OR_MONTHS`: `plan` ou `months` está ausente.
* `INVALID_MONTHS`: `months` não é `1`, `3` ou `12`, ou não é `1` para o plano Economy.
* `INVALID_PLAN`: o slug do plano não existe.
* `NOT_AN_UPGRADE`: para `type: "upgrade"`, o plano de destino não é maior que o atual.
* `PLAN_MISMATCH_FOR_RENEWAL`: para `type: "renew"`, o plano de destino não corresponde ao atual.
* `PENDING_ORDER_LIMIT_REACHED`: há pedidos não pagos em aberto em quantidade excessiva.
* `INTERNAL_SERVER_ERROR`: ocorreu um erro inesperado no servidor.

```json Error Response (400) theme={null}
{
  "code": "INVALID_PLAN"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.