> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Arquivar plano
> Encerra o plano para novas assinaturas. É definitivo, e não afeta quem já assinou.
`POST /plans/:id/archive`
Faz parte do recurso [Planos e Preços](/pt-BR/subscriptions/plans) — o conceito e os status estão
lá.
Move o plano para `archived`: ele deixa de aceitar novas assinaturas e passa a ser somente leitura.
A resposta é o plano já arquivado.
**Não há como desarquivar.** `archived` é terminal — nenhuma rota volta atrás, e o painel também
não. Para pausar as vendas de forma reversível, o caminho é deixar o plano `inactive` pelo painel;
a API não expõe essa transição.
**Quem já assinou continua sendo cobrado.** Arquivar fecha o catálogo, não os contratos: as
assinaturas em curso seguem emitindo faturas nos preços que contrataram. Para encerrar uma delas,
use [`POST /subscriptions/{id}/cancel`](/pt-BR/subscriptions/cancel).
**O `code` continua ocupado.** Arquivar não libera o código para reúso — criar um plano novo com o
mesmo `code` responde `409`. Use um código diferente, como um sufixo de ano ou de versão.
**Arquivar de novo não é erro.** A rota devolve `200` com o plano já arquivado — repetir a chamada
é seguro, e não há um `409` para o caso.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/plans/plan_lhutpqeq2ml3stia4vn90xars/archive \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"id": "plan_lhutpqeq2ml3stia4vn90xars",
"code": "pro-monthly",
"name": "Plano Pro",
"status": "archived",
"recurrence": {
"interval": 1,
"unit": "month",
"anchor": "subscription_start",
"collectionTiming": "prepaid"
},
"trialSpec": null,
"metadata": {},
"createdAt": "2026-08-10T13:45:30.000Z",
"updatedAt": "2026-08-10T14:20:05.000Z"
}
```
## OpenAPI
````yaml openapi/billing.json POST /plans/{id}/archive
openapi: 3.0.3
info:
title: Z2Pay Billing API
version: 1.0.0
description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Invoices
description: Faturas emitidas pelas assinaturas
- name: Plans
description: Planos de cobrança e versões de preço
- name: Subscriptions
description: Assinaturas recorrentes
paths:
/plans/{id}/archive:
post:
tags:
- Plans
summary: Arquivar plano
operationId: PlanController_archive
parameters:
- name: id
in: path
required: true
description: ID do plano
schema:
type: string
responses:
'200':
description: Plano arquivado
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
code:
type: string
description: >-
Código de identificação do recurso (ex.: código do plano
ou do contrato).
name:
type: string
description: Nome de exibição do plano ou do componente.
description:
type: string
nullable: true
description: Descrição do item (item do plano ou linha da fatura).
status:
type: string
description: >-
Status atual do registro (assinatura, fatura, plano ou
slip de pagamento).
recurrence:
type: object
nullable: true
description: >-
Cadência da cobrança: a cada quantas unidades
(`interval`), qual unidade (`unit`), a âncora do ciclo e
se cobra no início ou no fim. Vale para todos os itens
recorrentes.
trialSpec:
type: object
nullable: true
description: >-
Período de teste padrão da oferta. A assinatura pode
sobrescrevê-lo.
metadata:
type: object
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
example:
id: plan_lhutpqeq2ml3stia4vn90xars
code: pro-monthly
name: Pro Plan
description: Pro tier with all features
status: archived
recurrence:
interval: 1
unit: month
anchor: subscription_start
collectionTiming: prepaid
trialSpec: null
metadata: {}
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T15:00:00.000Z'
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Plano não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Plan not found
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````