Assinaturas

Consultar uma assinatura

GET /v1/subscriptions/{subscriptionId}

GET /v1/subscriptions/{subscriptionId}

Retorna os detalhes completos de uma assinatura, incluindo o ciclo vigente (currentCycle), itens, cliente, agenda de cobrança (billing) e splits. O parâmetro de URL aceita os prefixos subs_ e sub_.

Requisição

curl -X GET "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK

{
  "id": "subs_01hqzvabc",
  "status": "active",
  "currency": "BRL",
  "method": "credit",
  "type": "recurring",
  "currentCycle": {
    "id": "scy_01hqzvabc",
    "cycle": 1,
    "status": "paid",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-05-01T00:00:00.000Z",
    "dueDate": "2026-04-01T00:00:00.000Z",
    "billedAt": "2026-04-01T10:15:00.000Z",
    "updatedAt": "2026-04-01T10:15:00.000Z",
    "createdAt": "2026-04-01T00:00:00.000Z"
  },
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "birthdate": null,
    "gender": null,
    "document": { "type": "cpf", "number": "12345678901" },
    "telephone": { "countryCode": "55", "areaCode": "11", "number": "999999999", "line": "5511999999999" },
    "available": true,
    "delinquent": false,
    "externalReference": null,
    "additionalEmails": null,
    "metadata": null,
    "updatedAt": "2026-04-01T00:00:00.000Z",
    "createdAt": "2026-04-01T00:00:00.000Z"
  },
  "billing": {
    "frequency": "monthly",
    "frequencyCount": 1,
    "endDate": null,
    "exactDay": null,
    "freeTrialDays": null,
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": null,
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postcode": "01310100",
      "line": "Avenida Paulista, 1000, Bela Vista, São Paulo - SP, 01310100, BR",
      "fingerprint": null,
      "line1": "Avenida Paulista, 1000",
      "line2": null,
      "line3": "Bela Vista"
    }
  },
  "discount": null,
  "discounts": null,
  "shippable": false,
  "shipping": null,
  "spplited": false,
  "splits": null,
  "items": [
    {
      "id": "sit_01hqzvabc",
      "name": "Premium Plan",
      "description": null,
      "enabled": true,
      "pricingSchema": "recurring",
      "unitPrice": 9900,
      "quantity": 1,
      "currency": "BRL",
      "images": null,
      "metadata": null,
      "externalReference": null,
      "updatedAt": "2026-04-01T00:00:00.000Z",
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ],
  "callback": null,
  "geolocation": null,
  "externalReference": "ORDER-123",
  "metadata": { "campaign": "launch" },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc", "method": "GET", "description": "Read a subscription." },
    "cancel": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cancel", "method": "POST", "description": "Cancel the subscription." }
  }
}

Atributos da resposta

AtributoTipoDescrição
idstringIdentificador (subs_* / sub_*)
statusstringStatus da assinatura (ver Visão Geral)
methodstring | nullMétodo de pagamento
typestring | nullTipo (ex.: recurring)
currentCycleobject | nullCiclo de cobrança vigente
customerobjectDados do comprador (inclui additionalEmails como lista)
billingobjectAgenda de cobrança (frequency, frequencyCount, exactDay, freeTrialDays, endDate) + address
discountobject | nullBloco consolidado de desconto
discountsarray | nullCupons aplicados (snapshot)
splitsarray | nullSplits de receita
itemsarrayItens recorrentes
callbackobject | nullwebhookUrl + active
metadataobject | nullMetadados
merchantobjectname, merchantId, isSubAccount
_linksobjectself, cancel

Erros

error.codeHTTP
subscriptionNotFound404

Para listar várias assinaturas, veja Listar.

How is this guide?

On this page