Get Subscription

Get your current subscription status, including plan details, billing cycle, and credit caps.

Use this endpoint to check your billing status and what credits are available.

Subscription lifecycle: 1. After signup, status is none -- no data credits available. 2. After checkout, status is active -- full plan credits.

Request example

12curl https://api.v2.dealmachine.com/v1/subscription \
  -H "Authorization: Bearer dm_sk_live_xxx"

Response example

1234567891011121314151617181920212223242526272829{
  "status": "active",
  "plan": {
    "name": "Basic",
    "is_paid": true
  },
  "trial": {
    "is_trialing": false,
    "trial_end": null,
    "enrichment_credits": 0
  },
  "billing_cycle": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-05-01T00:00:00.000Z"
  },
  "credits": {
    "base_enrichment_cap": 10000,
    "monthly_credit_grant_cap": 0,
    "monthly_enrichment_cap": 10000,
    "additional_enrichment_balance": 0,
    "enrichment_cap": 10000,
    "total_enrichment_cap": 10000,
    "total_enrichment_available": 9998,
    "ai_cap": 25000000,
    "base_ai_cap": 25000000,
    "monthly_ai_credit_grant_cap": 0,
    "monthly_ai_cap": 25000000
  }
}

Response Fields

Field	Type	Description
`status`	string	Subscription status: `none`, `trialing`, `active`, `past_due`, `canceled`, `incomplete`, `unpaid`, `paused`
`plan.name`	string	Plan name (e.g., "Basic", "Pro", "No plan")
`plan.is_paid`	boolean	`true` if the subscription is active and paid
`trial.is_trialing`	boolean	`true` only for legacy Stripe subscriptions still in pre-billing status
`trial.trial_end`	string \| null	ISO 8601 timestamp when that status ends (null otherwise)
`trial.enrichment_credits`	number	Data credits available in that status (0 otherwise)
`billing_cycle.start`	string	ISO 8601 start of the current billing cycle
`billing_cycle.end`	string	ISO 8601 end of the current billing cycle
`credits.enrichment_cap`	number	Monthly data credits for this billing cycle
`credits.total_enrichment_cap`	number	Total current-cycle capacity, including additional credits
`credits.total_enrichment_available`	number	Live spendable data credits remaining
`credits.ai_cap`	number	Max AI credits (tokens) for this billing cycle

Use credits.total_enrichment_available for eligibility checks. It is a live remaining balance. credits.total_enrichment_cap and credits.enrichment_cap are allowances, not balances.

Status Values

Status	Meaning	Can use API?
`none`	No subscription -- just signed up	No (403)
`trialing`	Legacy pre-billing status	Yes
`active`	Paid subscription	Yes
`past_due`	Payment failed, grace period	Yes (limited)
`canceled`	Subscription canceled	No