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

> ## Agent Instructions
> Documentação das APIs da DeliveryVip, em português. Regras que mais quebram integrações: (1) Merchant API: faça polling em GET /merchant/v3/events:polling no máximo a cada 30 s por token; confirme todo evento recebido com POST /merchant/v3/events/acknowledgment e corpo [{"id": "<eventId>"}] (o campo lido é id, não eventId), inclusive eventos repetidos ou que o sistema não trata; deduplique por eventId; o evento é só um aviso, busque o pedido na orderURL. (2) Tokens client_credentials valem 24 h e não têm refresh_token: peça outro ao receber 401. (3) Webhooks: valide a assinatura HMAC sobre o corpo bruto e responda 2xx rápido; o polling é a reconciliação. (4) Open Delivery: host od.deliveryvip.com.br, um client_secret por loja, datas em UTC. (5) Fidelidade: o operador implementa 5 rotas assinadas com HMAC e chama o config push; o estorno precisa ser idempotente. (6) Partner API: scope dv.partner. Não invente endpoints: use a referência gerada das specs OpenAPI.

# Gerenciar assinatura das lojas

> Ative, cancele, avise, bloqueie e atualize contrato e plano da assinatura de uma loja.

Cada ação é uma chamada em `/partner/v2/merchants/{merchantId}/<ação>`. As de estado respondem `202 Accepted` com o ID da loja; a atualização responde `200 OK`.

| Ação | Endpoint | Exige status | Efeito |
| - | - | - | - |
| [Ativar](#ativar-assinatura) | `POST activate` | `TRIAL`, `TRIAL_EXPIRED` ou `CANCELLED` | Vai para `ACTIVATED`. |
| [Cancelar](#cancelar-assinatura) | `POST cancel` | `ACTIVATED` | Vai para `CANCELLED`. |
| [Ativar aviso](#ativar-aviso) | `POST warning` | `ACTIVATED` | `warning: true`, `blocked: false`. |
| [Desativar aviso](#desativar-aviso) | `POST unwarning` | `ACTIVATED` | `warning: false`. |
| [Bloquear](#bloquear-assinatura) | `POST block` | `ACTIVATED` | `blocked: true`, `warning: false`. |
| [Desbloquear](#desbloquear-assinatura) | `POST unblock` | `ACTIVATED` | `blocked: false`. |
| [Atualizar](#atualizar-assinatura) | `PUT subscription` | `TRIAL`, `ACTIVATED` ou `DEMO` | Troca `agreementCode` e/ou plano. |

```json Resposta (202) theme={null}
{ "merchantId": "d7240afd-d47c-4ae8-b79d-f14d3e8e1dd8" }
```

Quando o status não aceita a ação, a resposta é `422` com o motivo no `title`, por exemplo `{"status": "422", "title": "Subscription must be activated"}`. Loja fora do alcance do token retorna `404`.

## Ativar Assinatura

Tira a loja do teste ou reativa uma loja cancelada.

**subscription.agreementCode** `string`

Código do contrato. Omita (ou envie `null`) para manter o atual.

**subscription.planId** `uuid`

Plano de cobrança. Omita para manter o atual. Precisa ser um plano `AVAILABLE` do parceiro, com visibilidade compatível com a loja: `PUBLIC` ou `DIRECT_MERCHANT` para lojas diretas, `PUBLIC` ou `RESALE` para lojas de revenda. Veja [Planos](/docs/guides/partner/plans/definicoes.md).

```bash cURL theme={null}
curl --request POST 'https://api.deliveryvip.com.br/partner/v2/merchants/{merchantId}/activate' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscription": {
      "agreementCode": "123456",
      "planId": "47f3af9c-c380-4e09-8f73-76bc06634d76"
    }
  }'
```

```js Node.js theme={null}
await fetch(`https://api.deliveryvip.com.br/partner/v2/merchants/${merchantId}/activate`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ subscription: { agreementCode: '123456', planId } }),
})
```

```python Python theme={null}
requests.post(
    f"https://api.deliveryvip.com.br/partner/v2/merchants/{merchant_id}/activate",
    headers={"Authorization": f"Bearer {token}"},
    json={"subscription": {"agreementCode": "123456", "planId": plan_id}},
)
```

A ativação é recusada com `422` quando:

* a loja é `DEMO` (`Subscription is demo`);
* a assinatura do parceiro ou da revenda da loja não está `ACTIVATED` (`Partner subscription is not activated`);
* o `planId` não existe, não está disponível ou não é visível para a loja (`Invalid plan`);
* a loja já está `ACTIVATED`.

> [!WARNING]
>
> **Reativação no mesmo mês do cancelamento.** Se a loja foi cancelada no mês corrente (ou há menos de 24 horas), a reativação muda o status, mas mantém `lastActivationAt` e **ignora** `agreementCode` e `planId`. Envie-os em seguida com [Atualizar Assinatura](#atualizar-assinatura).

## Cancelar Assinatura

Encerra a assinatura. Não tem corpo.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/partner/v2/merchants/{merchantId}/cancel' \
  --header 'Authorization: Bearer {token}'
```

> [!CAUTION]
>
> O cancelamento também cancela todos os recursos contratados e **remove os domínios da loja**. Ao reativar, o domínio padrão é recriado, mas domínios personalizados precisam ser configurados de novo.

## Ativar Aviso

Sinaliza que a loja pode ser bloqueada em breve, por exemplo por atraso de pagamento. Não tem corpo. Desliga um bloqueio ativo.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/partner/v2/merchants/{merchantId}/warning' \
  --header 'Authorization: Bearer {token}'
```

## Desativar Aviso

Remove o aviso. Não tem corpo: `POST /partner/v2/merchants/{merchantId}/unwarning`.

## Bloquear Assinatura

Bloqueia o uso da loja. Não tem corpo: `POST /partner/v2/merchants/{merchantId}/block`.

> [!NOTE]
>
> O bloqueio não cancela: a assinatura continua `ACTIVATED` e continua sendo cobrada. Use o bloqueio para inadimplência, não como cancelamento.

## Desbloquear Assinatura

Libera a loja. Não tem corpo: `POST /partner/v2/merchants/{merchantId}/unblock`.

## Atualizar Assinatura

Troca o código do contrato, o plano ou os dois, sem mudar o status. Aceita lojas em `TRIAL`, `ACTIVATED` ou `DEMO`; nos demais status responde `422` (`Failed to update subscription`).

**subscription.agreementCode** `string`

Código do contrato. Omita (ou envie `null`) para manter; envie `""` para apagar.

**subscription.planId** `uuid`

Novo plano. Mesmas regras de visibilidade da ativação. Plano inválido retorna `422`.

```bash cURL theme={null}
curl --request PUT 'https://api.deliveryvip.com.br/partner/v2/merchants/{merchantId}/subscription' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscription": {
      "agreementCode": "123456",
      "planId": "47f3af9c-c380-4e09-8f73-76bc06634d76"
    }
  }'
```

```js Node.js theme={null}
await fetch(`https://api.deliveryvip.com.br/partner/v2/merchants/${merchantId}/subscription`, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ subscription: { agreementCode: '123456', planId } }),
})
```

```python Python theme={null}
requests.put(
    f"https://api.deliveryvip.com.br/partner/v2/merchants/{merchant_id}/subscription",
    headers={"Authorization": f"Bearer {token}"},
    json={"subscription": {"agreementCode": "123456", "planId": plan_id}},
)
```

```json Resposta (200) theme={null}
{ "merchantId": "d7240afd-d47c-4ae8-b79d-f14d3e8e1dd8" }
```

Ao trocar de plano, os recursos da loja são sincronizados com o novo plano.

## Código do Contrato

> [!WARNING]
>
> `PUT /partner/v2/merchants/{merchantId}/agreementCode` está **descontinuado** em favor de [Atualizar Assinatura](#atualizar-assinatura). A data de desligamento anunciada foi 01/07/2025; a rota ainda responde, com os headers `Deprecation: true` e `Sunset: Tue, 01 Jul 2025 00:00:00 GMT`, e pode ser removida a qualquer momento.

Aceita o mesmo corpo de `PUT subscription` e responde igual. Migre trocando apenas o final do caminho.


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