---
title: "Criar assinatura a partir de um Plano"
method: POST
path: "/recurrence/subscriptions/"
tags: ["Assinaturas"]
---

# Criar assinatura a partir de um Plano

`POST /recurrence/subscriptions/`

## Request body

- SubscriptionCreationDTO
  - `plan_id` string, nullable — Id do Plano. Obrigatório se for uma assinatura de plano.
  - `customer` ZpyEnterpriseResourcesDomainPaymentOrderModelValueObjectsOrderValueObjectsCustomer
    - `name` string, required
    - `email` string, nullable
    - `phone` string, nullable
    - `document` string, nullable
    - `birthdate` string, date-time, nullable
    - `address` CustomerAddress
      - `zip_code` string, required
      - `line_1` string, required
      - `line_2` string, nullable, required
      - `state` string, required
      - `city` string, required
      - `metadata` object, nullable
    - `external_id` string, nullable
    - `metadata` object, nullable
  - `customer_id` string, nullable — Id do cliente. Obrigatório caso o customer não seja informado.
  - `installments` integer — Quantidade de parcelas aplicáveis quando o método de pagamento da assinatura for cartão de crédito.
  - `card` ZpyEnterpriseResourcesDomainPaymentTransactionModelValueObjectsCardValueObjectsCard
    - `number` string, nullable
    - `holder_name` string, nullable
    - `holder_document` string, nullable
    - `exp_month` integer, nullable
    - `exp_year` integer, nullable
    - `cvv` string, nullable
    - `brand` string, nullable
    - `billing_address` CardBillingAddress
      - `zip_code` string, required
      - `line_1` string, nullable
      - `line_2` string, nullable
      - `state` string, required
      - `city` string, required
    - `card_hash` string, nullable
  - `card_token` string, nullable — Token do cartão gerado pelo checkout.
  - `payment_method` string, required — Meio de pagamento. Valores possíveis: credit_card, boleto, voucher e pix.
  - `external_id` string, nullable — Id externo.
  - `name` string, nullable — Nome da assinatura.
  - `interval` string, nullable — Frequência da recorrência. Valores possíveis: day, week, month ou year.
  - `interval_count` integer, nullable — Número de intervalos de acordo com a propriedade interval entre cada cobrança da assinatura. Ex.: plano mensal = interval_count (1) e interval (month) plano trimestral = interval_count (3) e interval (month) plano semestral = interval_count (6) e interval (month)
  - `interval_free` integer, nullable — Número de intervalo no qual a cobrança é gratuita. Ex.: interval_free (1) e interval (month) a primeira cobrança é gratuita.
  - `billing_type` string, nullable — Tipo de cobrança. Valores possíveis: prepaid, postpaid ou exact_day.
  - `items` SubscriptionItemDTO[], nullable — Itens do plano.
    - `product_id` string, required — Id do produto.
    - `amount` union, required — Valor unitário do produto
      - number
      - string
    - `description` string — Descrição do produto
    - `type` string — Tipo do produto
    - `status` string — Status do item
    - `metadata` object — Dados adicionais do produto
  - `metadata` object, nullable — Objeto chave/valor utilizado para armazenar informações adicionais sobre o pagamento
  - `first_payment` FirstPaymentDTOInput
    - `amount` union — Valor do primeiro pagamento (opcional).
      - number
      - string
    - `due_date` string, date-time, nullable — Data de vencimento do primeiro pagamento (opcional).
  - `payment_method_params` PaymentMethodParamsDTO
    - `acceptance_deadline` string, date-time, nullable — Prazo de aceitação do pagamento (opcional).
    - `type` string, nullable — Tipo de pagamento PIX. Valores possíveis: qrcode_and_payment, payment_and_or_qrcode. Obrigatório quando payment_method=pix.

## Response `200`

Assinatura criada com sucesso

- SubscriptionCreatedDTO
  - `subscription_id` string, required — Id da assinatura.
  - `payment_method` string, required — Meio de pagamento utilizado na assinatura.
  - `interval_count` integer, required — Número de intervalos de acordo com a propriedade interval entre cada cobrança da assinatura. Ex.: plano mensal = interval_count (1)
  - `plan_id` string, nullable — Id do plano assinado.
  - `current_cycle` SubscriptionCurrentCycleDTOOutput, required
    - `start_at` string, date-time, required — Data inicial da asssinatura.
    - `end_at` string, date-time, nullable — Data final da asssinatura.
  - `billing_type` string, required
  - `next_billing_at` string, date-time — Data do próximo faturamento da assinatura.
  - `installments` integer, nullable — Quantidade de parcelas aplicádas ao cartão de crédito.
  - `customer` ZpyEnterpriseResourcesDomainPaymentOrderModelValueObjectsOrderValueObjectsCustomer
    - `name` string, required
    - `email` string, nullable
    - `phone` string, nullable
    - `document` string, nullable
    - `birthdate` string, date-time, nullable
    - `address` CustomerAddress
      - `zip_code` string, required
      - `line_1` string, required
      - `line_2` string, nullable, required
      - `state` string, required
      - `city` string, required
      - `metadata` object, nullable
    - `external_id` string, nullable
    - `metadata` object, nullable
  - `card` ZpyEnterpriseResourcesDomainPaymentOrderDtosOrderResponseDtosCardResponseDTO
    - `last_four_digits` union, required
      - string
      - integer
    - `brand` string, nullable, required
    - `holder_name` string, nullable, required
    - `exp_month` integer, nullable, required
    - `exp_year` integer, nullable, required
    - `status` string, nullable
    - `billing_address` ZpyEnterpriseResourcesDomainPaymentOrderDtosOrderResponseDtosAddressResponseDTO, required
      - `zip_code` string, required
      - `state` string, required
      - `city` string, required
      - `line_1` string, nullable
      - `line_2` string, nullable
      - `metadata` object
    - `type` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `external_id` string, nullable — Id externo.
  - `items` PlanItemCreatedDTO[], required
    - `product_id` string, required — Id do produto criado.
    - `amount` string, required — Valor unitário do produto criado
    - `description` string — Descrição do produto criado
    - `type` string — Tipo do produto criado
    - `status` string — Status do item criado
    - `metadata` object — Dados adicionais do produto criado
  - `status` string
  - `created_at` string, date-time, required — Data de criação da assinatura.
  - `updated_at` string, date-time, required — Data de atualização da assinatura.
  - `metadata` object, nullable — Dados adicionais da assinatura.
  - `first_payment` FirstPaymentDTOOutput
    - `amount` string, nullable — Valor do primeiro pagamento (opcional).
    - `due_date` string, date-time, nullable — Data de vencimento do primeiro pagamento (opcional).
  - `payment_method_params` PaymentMethodParamsDTO
    - `acceptance_deadline` string, date-time, nullable — Prazo de aceitação do pagamento (opcional).
    - `type` string, nullable — Tipo de pagamento PIX. Valores possíveis: qrcode_and_payment, payment_and_or_qrcode. Obrigatório quando payment_method=pix.
  - `payment_method_data` PaymentMethodDataDTO
    - `qr_code_url` string, nullable — URL do QR Code PIX (opcional, apenas para PIX).
    - `qr_code_data` string, nullable — Dados do QR Code PIX em base64 (opcional, apenas para PIX).
    - `expiration_date` string, date-time, nullable — Data de expiração do QR Code PIX (opcional, apenas para PIX).

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/usezapay/apis/zapi.md) · [All operations](https://skmtc.net/usezapay/apis/zapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usezapay/zapi/versions/50c96157fff4/schema)