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.
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