> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Buscar uma assinatura
> Retorna os dados de uma assinatura (`subs_...`).
Informe ao menos um entre `id`, `externalId` e `customerId`. Sem nenhum deles, a API retorna `Provide id, externalId or customerId`. Quando o filtro casa mais de uma assinatura (por exemplo, um cliente com várias), a mais recente é retornada.
Para buscar o checkout de assinatura (`bill_...`), use `GET /subscriptions/checkouts/get`.
Retorna os dados de uma assinatura (`subs_...`).
Requer a permissão `SUBSCRIPTION:READ`.
Informe ao menos um destes filtros:
| Parâmetro | Descrição |
| ------------ | ------------------------------------------------------------------ |
| `id` | ID da assinatura (`subs_...`) |
| `externalId` | O `externalId` que você informou ao criar o checkout de assinatura |
| `customerId` | ID do cliente (`cust_...`) |
Sem nenhum deles, a API retorna `Provide id, externalId or customerId`. Quando o filtro casa mais de uma assinatura (por exemplo, um cliente com várias), a mais recente é retornada.
O campo `checkoutId` da resposta aponta o checkout de assinatura (`bill_...`) que originou a assinatura.
Para buscar o checkout de assinatura (`bill_...`), antes ou depois do pagamento, use [Buscar checkout de assinatura](/pages/subscriptions/checkouts-get).
## OpenAPI
````yaml GET /subscriptions/get
openapi: 3.1.0
info:
title: API AbacatePay
description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
version: 1.0.0
servers:
- url: https://api.abacatepay.com/v2
description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
/subscriptions/get:
get:
summary: Buscar uma assinatura
description: >
Retorna os dados de uma assinatura (`subs_...`).
Informe ao menos um entre `id`, `externalId` e `customerId`. Sem nenhum
deles, a API retorna `Provide id, externalId or customerId`. Quando o
filtro casa mais de uma assinatura (por exemplo, um cliente com várias),
a mais recente é retornada.
Para buscar o checkout de assinatura (`bill_...`), use `GET
/subscriptions/checkouts/get`.
parameters:
- name: id
in: query
description: Identificador único da assinatura
required: false
schema:
type: string
example: subs_abc123xyz
- name: externalId
in: query
description: >-
`externalId` informado ao criar o checkout de assinatura que
originou a assinatura
required: false
schema:
type: string
example: assinatura-123
- name: customerId
in: query
description: Identificador do cliente dono da assinatura
required: false
schema:
type: string
example: cust_abc123xyz
responses:
'200':
description: Assinatura encontrada com sucesso.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Subscription'
error:
type: string
nullable: true
example: null
success:
$ref: '#/components/schemas/Success'
'401':
description: Não autorizado. Falha na autenticação.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem de erro descrevendo o motivo da falha na
autenticação.
example: Token de autenticação inválido ou ausente.
'404':
description: Assinatura não encontrada.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Subscription not found
security:
- bearerAuth: []
components:
schemas:
Subscription:
type: object
description: >-
Dados de uma assinatura (`subs_...`). Existe a partir do pagamento do
checkout de assinatura que a originou (`checkoutId`).
required:
- id
- checkoutId
- customerId
- amount
- status
- method
- coupons
- devMode
- trialDays
- trialEndsAt
- retryPolicy
- createdAt
- updatedAt
additionalProperties: false
properties:
id:
type: string
description: Identificador único da assinatura.
example: subs_abc123xyz
checkoutId:
type: string
nullable: true
description: >-
Checkout de assinatura (`bill_...`) que originou a assinatura. Um
checkout pode originar várias assinaturas, uma por cliente pagante.
example: bill_abc123xyz
customerId:
type: string
description: Identificador do cliente que possui a assinatura.
example: cust_abc123xyz
amount:
type: number
description: Valor da assinatura em centavos.
example: 10000
status:
type: string
description: Status atual da assinatura.
enum:
- PENDING
- ACTIVE
- CANCELLED
example: ACTIVE
method:
type: string
description: Método de pagamento da assinatura.
enum:
- PIX
- CARD
example: CARD
coupons:
type: array
items:
type: string
description: Cupons aplicados.
example: []
devMode:
type: boolean
description: Indica se a assinatura foi criada em ambiente de testes.
example: false
trialDays:
type: integer
nullable: true
description: Duração do período de teste em dias; `null` sem trial.
example: null
trialEndsAt:
type: string
format: date-time
nullable: true
description: Fim do período de teste; `null` sem trial.
example: null
retryPolicy:
type: object
description: Política de retentativa de cobrança.
properties:
maxRetry:
type: integer
example: 3
retryEvery:
type: integer
example: 1
createdAt:
type: string
format: date-time
description: Data de criação da assinatura.
example: '2024-11-04T18:38:28.573Z'
updatedAt:
type: string
format: date-time
description: Data de atualização da assinatura.
example: '2024-11-04T18:38:28.573Z'
Success:
type: boolean
description: Se a requisição obteve sucesso ou não.
example: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Todas as requisições devem incluir sua chave de API no header
Authorization usando o formato `Bearer `. Sem esse
header a requisição será rejeitada.
Saiba mais sobre como criar e usar chaves de API na [documentação de
autenticação](/pages/authentication).
````