Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.linkutm.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Billing runs on Dodo Payments. Endpoints live under /api/v1/payments. Most are workspace-scoped and require the x-workspace-id header plus workspace admin access. Plan listings are public. 
Authorization: Bearer <jwt>
x-workspace-id: <uuid_or_slug>

​
Plans

​
List plans

GET /api/v1/payments/plans
Public. Returns all active plans.

​
Get a plan

GET /api/v1/payments/plans/:id
Public. Returns one plan by ID.

​
Plan fields

FieldTypeNotes
pricenumberMonthly price.
yearlyPricenumberYearly price.
currencystringISO currency code.
badgestring | nullDisplay badge, e.g. Popular.
maxLinksintegerLink maximum.
maxClicksintegerTracked-click maximum per period.
maxApiCallsintegerAPI call maximum per period.
maxTeamMembersintegerTeam member maximum.
maxDomainsintegerCustom domain maximum.
maxFoldersintegerFolder maximum.
maxTagsintegerTag maximum.
maxUtmTemplatesintegerUTM template maximum.
maxQrCodesintegerQR code maximum.
maxPasswordProtectedLinksintegerPassword-protected link maximum.
analyticsRetentionintegerAnalytics retention window (days).
featuresobjectFeature flags (JSON).

​
Checkout

POST /api/v1/payments/checkout
Requires workspace admin access. Returns a Dodo-hosted checkout URL.
​
planId
string
required
UUID of the target plan.
​
billingCycle
string
default:"monthly"
monthly or yearly.
​
workspaceId
string
Target workspace. Defaults to the workspace in x-workspace-id.
Redirect the user to the returned URL to complete payment.

​
Confirm checkout

POST /api/v1/payments/confirm
​
subscriptionId
string
required
The subscription ID returned by the checkout flow.
Finalizes the subscription after the user returns from the Dodo checkout.

​
Customer portal

POST /api/v1/payments/portal
Returns a Dodo customer-portal URL where the user can manage payment methods and billing details.

​
Subscription

​
Get current subscription

GET /api/v1/payments/subscription
Returns the current workspace subscription. 
GET /api/v1/payments/subscription/details
Same, plus the linked Dodo subscription data.

​
Subscription fields

FieldTypeNotes
statusstringSubscription state.
billingCyclestringmonthly or yearly.
currentPeriodStarttimestampStart of the current billing period.
currentPeriodEndtimestampEnd of the current billing period.
cancelAtPeriodEndbooleantrue if a cancellation is scheduled.
linksUsedintegerLinks consumed this period.
clicksUsedintegerClicks tracked this period.
apiCallsUsedintegerAPI calls made this period.
The record also carries pending plan and cycle fields when a downgrade or cycle change is scheduled.

​
Cancel

POST /api/v1/payments/subscription/cancel
Cancels the subscription. It typically stays active until currentPeriodEnd (cancelAtPeriodEnd becomes true).

​
Plan changes

​
Schedule a downgrade

POST /api/v1/payments/subscription/schedule-downgrade
​
planId
string
required
Target (lower) plan UUID.
​
billingCycle
string
required
monthly or yearly.

​
Downgrade preview

GET /api/v1/payments/subscription/downgrade-preview?planId=<uuid>
Returns the resources that exceed the target plan’s limits, so the user can decide what to keep.

​
Execute a downgrade

POST /api/v1/payments/subscription/downgrade-execute
Applies the downgrade. You choose which resources to keep within the new limits; the rest are deactivated.
​
planId
string
required
Target plan UUID.
​
billingCycle
string
required
monthly or yearly.
​
keepDomainIds
string[]
required
Domain UUIDs to keep.
​
keepMemberIds
string[]
required
Team member UUIDs to keep.
​
keepTemplateIds
string[]
required
UTM template UUIDs to keep.
​
keepTagIds
string[]
required
Tag UUIDs to keep.
​
keepFolderIds
string[]
required
Folder UUIDs to keep.
Resources not listed in the keep* arrays are deactivated when the downgrade executes. Use downgrade-preview first to see exactly what exceeds the target plan.

​
Upgrade activation preview

GET /api/v1/payments/subscription/upgrade-activation-preview?planId=<uuid>
Returns previously deactivated resources that can be reactivated on the higher target plan.

​
Save upgrade selections

POST /api/v1/payments/subscription/save-upgrade-selections
Records which deactivated resources to reactivate on upgrade.
​
planId
string
required
Target plan UUID.
​
memberIds
string[]
Team member UUIDs to reactivate.
​
domainIds
string[]
Domain UUIDs to reactivate.
​
tagIds
string[]
Tag UUIDs to reactivate.
​
folderIds
string[]
Folder UUIDs to reactivate.
​
templateIds
string[]
UTM template UUIDs to reactivate.

​
Billing history

​
Payment history

GET /api/v1/payments/history
Returns the workspace’s payment history.

​
Download an invoice

GET /api/v1/payments/invoice/:id/download
Streams the invoice PDF for the given payment.

​
Sync history

POST /api/v1/payments/history/sync
Pulls the latest payment records from Dodo into the workspace.

​
Plan, usage & features

​
Current plan and usage

GET /api/v1/payments/plan
Returns the workspace’s current plan together with usage figures.

​
All usage limits

GET /api/v1/payments/usage
Returns usage against every limit.

​
A single limit

GET /api/v1/payments/usage/:limitType
limitType is one of: links, clicks, apiCalls, teamMembers, domains, folders, tags, utmTemplates, passwordProtectedLinks.

​
Feature check

GET /api/v1/payments/feature/:featureKey
Returns whether the workspace’s plan unlocks the given feature. 
{ "feature": "custom_domains", "allowed": true }

​
Webhook

POST /api/v1/payments/webhook
The endpoint Dodo Payments calls for subscription and payment events. Signatures are verified internally by @dodopayments/express - this endpoint is for Dodo, not for client integrations.

​
Errors

CodeWhen
400Invalid planId, billingCycle, or missing fields
401Missing or invalid JWT
403Caller is not a workspace admin
404Plan, subscription, or workspace not found
429Rate limit exceeded (100 requests/minute per IP)
See Errors for the full error envelope.