Billing & Payments API

Manage workspace subscriptions, process payments via PayTR, view invoices, and validate coupons.

Initiate Checkout

Creates a PayTR payment session and returns an iFrame URL.

POST /api/workspaces/{slug}/billing/checkout/

Request Body:

Field	Type	Description
plan_slug	string	Plan identifier (e.g., pro, business)
billing_interval	string	month or year
coupon_code	string	Optional discount code

Response:

{
  "iframe_token": "abc123...",
  "iframe_url": "https://www.paytr.com/odeme/guvenli/abc123...",
  "merchant_oid": "SG-c86cd04d-1712567890123",
  "amount": 9990,
  "currency": "TL"
}

Embed the iframe_url in an <iframe> to display the PayTR payment form.

Get Subscription

Returns the active subscription and workspace limits.

GET /api/workspaces/{slug}/billing/subscription/

Response:

{
  "subscription": {
    "id": "sub_id",
    "plan_slug": "pro",
    "status": "active",
    "billing_interval": "month",
    "currency": "TL",
    "amount_per_period": 9990,
    "current_period_start": "2026-04-08T00:00:00Z",
    "current_period_end": "2026-05-08T00:00:00Z",
    "cancel_at_period_end": false
  },
  "limits": {
    "plan_slug": "pro",
    "plan_name": "SetGet Pro",
    "max_users": -1,
    "max_projects": -1,
    "max_storage_gb": 100,
    "ai_tokens_monthly": 50000,
    "features": { "time_tracking": true, "custom_properties": true },
    "is_active": true
  }
}

When no subscription exists, subscription is null and limits returns free tier defaults.

Cancel Subscription

POST /api/workspaces/{slug}/billing/cancel/

Request Body:

Field	Type	Description
immediate	boolean	true = cancel now, false = cancel at period end

List Invoices

GET /api/workspaces/{slug}/billing/invoices/?offset=0&per_page=20

Response:

{
  "results": [
    {
      "id": "inv_id",
      "invoice_number": "INV-2026-000001",
      "plan_name": "SetGet Pro",
      "billing_interval": "month",
      "total_amount": 9990,
      "currency": "TL",
      "period_start": "2026-04-08T00:00:00Z",
      "period_end": "2026-05-08T00:00:00Z",
      "created_at": "2026-04-08T12:00:00Z"
    }
  ],
  "total": 1
}

List Payments

GET /api/workspaces/{slug}/billing/payments/?offset=0&per_page=20

Returns payment history including status (pending, success, failed, refunded).

Validate Coupon

POST /api/workspaces/{slug}/billing/validate-coupon/

Request Body:

{
  "code": "WELCOME20",
  "plan_slug": "pro",
  "amount": 9990
}

Response:

{
  "valid": true,
  "discounted_amount": 7992,
  "discount_display": "-19.98"
}

PayTR Callback (Webhook)

PayTR sends payment results to this endpoint. Do not call this directly.

POST /api/webhooks/paytr/callback/

This endpoint is public (no authentication). It verifies the PayTR hash signature and responds with plain text OK.

Subscription Statuses

Status	Description
trialing	Free trial period
active	Paid and active
past_due	Payment failed, in grace period
suspended	Grace period expired
canceled	User-initiated cancellation
expired	Subscription term ended