Skip to main content
GET
/
api
/
subscriptions
Listar Assinaturas
curl --request GET \
  --url https://garu.com.br/api/subscriptions \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {}
  ],
  "count": 123,
  "totalCount": 123,
  "page": 123,
  "totalPages": 123
}

​
Visão Geral

Este endpoint retorna uma lista paginada de todas as assinaturas. Você pode filtrar por status, cliente, produto e buscar por nome ou email do cliente.

​
Exemplo de Requisição

curl -X GET "https://garu.com.br/api/subscriptions?status=active&page=1&limit=20" \
  -H "Authorization: Bearer sk_test_sua_chave"

​
Parâmetros de Query

​
page
integer
default:"1"
Número da página para paginação.
​
limit
integer
default:"20"
Quantidade de itens por página.
​
status
string
Filtrar por status: pending, active, pending_cancellation, canceled, failed.
​
customerId
integer
Filtrar por ID do cliente.
​
productId
integer
Filtrar por ID do produto.
​
search
string
Buscar por nome ou email do cliente.

​
Resposta de Sucesso

​
data
array
Lista de assinaturas.
​
count
number
Total de assinaturas retornadas nesta página.
​
totalCount
number
Total de assinaturas que correspondem aos filtros.
​
page
number
Página atual.
​
totalPages
number
Total de páginas disponíveis.

​
Exemplo de Resposta (200 OK)

{
  "data": [
    {
      "id": 100,
      "uuid": "sub_xyz789",
      "customerId": 50,
      "subscriptionPriceId": 456,
      "status": "active",
      "currentPeriodStart": "2024-02-15T00:00:00.000Z",
      "currentPeriodEnd": "2024-03-15T00:00:00.000Z",
      "trialEndsAt": null,
      "cancelAt": null,
      "lastPaymentAt": "2024-02-15T10:00:00.000Z",
      "nextPaymentAt": "2024-03-15T10:00:00.000Z",
      "customer": {
        "id": 50,
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "subscriptionPrice": {
        "id": 456,
        "name": "Plano Mensal",
        "unitAmount": 49.90,
        "billingInterval": "monthly"
      }
    },
    {
      "id": 101,
      "uuid": "sub_abc123",
      "customerId": 51,
      "subscriptionPriceId": 457,
      "status": "active",
      "currentPeriodStart": "2024-02-10T00:00:00.000Z",
      "currentPeriodEnd": "2025-02-10T00:00:00.000Z",
      "trialEndsAt": null,
      "cancelAt": null,
      "lastPaymentAt": "2024-02-10T10:00:00.000Z",
      "nextPaymentAt": "2025-02-10T10:00:00.000Z",
      "customer": {
        "id": 51,
        "name": "Maria Santos",
        "email": "maria@email.com"
      },
      "subscriptionPrice": {
        "id": 457,
        "name": "Plano Anual",
        "unitAmount": 479.00,
        "billingInterval": "yearly"
      }
    }
  ],
  "count": 2,
  "totalCount": 50,
  "page": 1,
  "totalPages": 25
}

​
Status de Assinatura

StatusDescrição
pendingAguardando primeiro pagamento
activeAssinatura ativa e em dia
pending_cancellationCancelamento agendado para fim do período
canceledAssinatura encerrada
failedPagamento falhou após todas as tentativas

​
Paginação

Para percorrer todas as assinaturas: 
async function listarTodasAssinaturas(status = 'active') {
  const assinaturas = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://garu.com.br/api/subscriptions?status=${status}&page=${page}&limit=50`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.GARU_API_KEY}`
        }
      }
    );

    const result = await response.json();
    assinaturas.push(...result.data);
    totalPages = result.totalPages;
    page++;
  } while (page <= totalPages);

  return assinaturas;
}

​
Próximos Passos

Detalhes da Assinatura

Consulte os detalhes completos de uma assinatura

Gerenciar Assinaturas

Cancelar, pausar e retomar assinaturas