Skip to main content
GET
/
api
/
subscriptions
/
{id}
Detalhes da Assinatura
curl --request GET \
  --url https://garu.com.br/api/subscriptions/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": 123,
  "uuid": "<string>",
  "status": "<string>",
  "currentPeriodStart": "<string>",
  "currentPeriodEnd": "<string>",
  "trialEndsAt": {},
  "cancelAt": {},
  "cancelAtPeriodEnd": true,
  "nextPaymentAt": "<string>",
  "lastPaymentAt": "<string>",
  "failedPaymentCount": 123,
  "subscriptionPrice": {},
  "customer": {},
  "paymentMethod": {}
}

​
Visão Geral

Este endpoint retorna os detalhes completos de uma assinatura específica, incluindo informações do cliente, preço, método de pagamento e histórico de eventos.

​
Exemplo de Requisição

curl -X GET https://garu.com.br/api/subscriptions/100 \
  -H "Authorization: Bearer sk_test_sua_chave"

​
Resposta de Sucesso

​
id
number
ID interno da assinatura.
​
uuid
string
Identificador único da assinatura.
​
status
string
Status atual: pending, active, pending_cancellation, canceled, failed.
​
currentPeriodStart
string
Início do período de cobrança atual (ISO 8601).
​
currentPeriodEnd
string
Fim do período de cobrança atual (ISO 8601).
​
trialEndsAt
string | null
Data de término do período de teste.
​
cancelAt
string | null
Data agendada para cancelamento.
​
cancelAtPeriodEnd
boolean
Se o cancelamento ocorrerá ao fim do período.
​
nextPaymentAt
string
Data da próxima cobrança.
​
lastPaymentAt
string
Data do último pagamento.
​
failedPaymentCount
number
Número de tentativas de pagamento falhas.
​
subscriptionPrice
object
Detalhes do preço/plano da assinatura.
​
customer
object
Dados do cliente.
​
paymentMethod
object
Método de pagamento associado.

​
Exemplo de Resposta (200 OK)

{
  "id": 100,
  "uuid": "sub_xyz789",
  "customerId": 50,
  "subscriptionPriceId": 456,
  "sellerId": 1,
  "status": "active",
  "currentPeriodStart": "2024-02-15T00:00:00.000Z",
  "currentPeriodEnd": "2024-03-15T00:00:00.000Z",
  "trialEndsAt": null,
  "cancelAt": null,
  "cancelledAt": null,
  "cancelAtPeriodEnd": false,
  "paymentMethodId": 789,
  "lastPaymentAt": "2024-02-15T10:00:00.000Z",
  "nextPaymentAt": "2024-03-15T10:00:00.000Z",
  "failedPaymentCount": 0,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-02-15T10:00:00.000Z",
  "subscriptionPrice": {
    "id": 456,
    "uuid": "price_def456uvw",
    "name": "Plano Mensal",
    "unitAmount": 49.90,
    "billingInterval": "monthly",
    "product": {
      "id": 123,
      "name": "Premium Membership"
    }
  },
  "customer": {
    "id": 50,
    "name": "João Silva",
    "email": "joao@example.com"
  },
  "paymentMethod": {
    "id": 789,
    "cardLast4": "4242",
    "cardBrand": "visa"
  }
}

​
Exemplo Completo

async function verificarStatusAssinatura(subscriptionId) {
  const response = await fetch(
    `https://garu.com.br/api/subscriptions/${subscriptionId}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.GARU_API_KEY}`
      }
    }
  );

  const subscription = await response.json();

  // Verificar se está ativa
  const isActive = subscription.status === 'active';

  // Verificar se está em período de teste
  const inTrial = subscription.trialEndsAt &&
    new Date(subscription.trialEndsAt) > new Date();

  // Verificar se tem cancelamento agendado
  const willCancel = subscription.cancelAtPeriodEnd ||
    subscription.status === 'pending_cancellation';

  return {
    isActive,
    inTrial,
    willCancel,
    nextPayment: subscription.nextPaymentAt,
    plan: subscription.subscriptionPrice.name,
    customer: subscription.customer
  };
}

// Uso
const status = await verificarStatusAssinatura(100);
if (status.isActive) {
  console.log(`Assinatura ativa: ${status.plan}`);
  console.log(`Próxima cobrança: ${status.nextPayment}`);
}

​
Próximos Passos

Eventos da Assinatura

Histórico de eventos e pagamentos

Cancelar Assinatura

Cancele uma assinatura

Pausar Assinatura

Pause temporariamente as cobranças

Portal do Cliente

Autoatendimento para assinantes