Admin (test mode only)

Admin endpoints are scoped to test-mode keys only (sk_test_). They’re not available in production. Calling them with a live key returns 403 Forbidden.

GET /admin/clock

Get the current simulated time for your sandbox tenant.

curl https://api.useplinth.com/admin/clock \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY"

Response

{
  "simulated_now": "2026-06-01T00:00:00Z",
  "real_now": "2026-06-18T10:23:44Z",
  "offset_seconds": 0
}

POST /admin/clock/advance

Advance the simulated clock by a number of seconds.

curl -X POST https://api.useplinth.com/admin/clock/advance \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds": 2592000}'

Request body

number

required

Number of seconds to advance. Must be positive. Max: 31536000 (1 year) per call.

Response

{
  "simulated_now": "2026-07-01T00:00:00Z",
  "advanced_seconds": 2592000
}

Advancing the clock alone doesn’t trigger billing. Follow with POST /admin/tick.

POST /admin/tick

Run the billing engine for your tenant at the current simulated time. This processes subscription renewals, dunning retries, grace expiries, and state transitions.

curl -X POST https://api.useplinth.com/admin/tick \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY"

Response

{
  "processed_subscriptions": 3,
  "invoices_created": 2,
  "invoices_paid": 1,
  "state_transitions": [
    {
      "subscription_id": "sub_01JABC...",
      "from": "active",
      "to": "past_due",
      "reason": "card_declined"
    }
  ],
  "webhooks_fired": ["subscription.past_due", "invoice.created"]
}

GET /admin/suspense

List transfers that arrived but couldn’t be matched to an open invoice.

curl https://api.useplinth.com/admin/suspense \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY"

Response

{
  "items": [
    {
      "id": "susp_01JABC...",
      "customer_id": "cus_01JXYZ...",
      "amount_minor": 500000,
      "received_at": "2026-06-05T09:14:00Z",
      "reason": "no_open_invoice"
    }
  ]
}

POST /admin/suspense/:id/resolve

Manually apply a suspense transfer to a specific invoice, or credit it to the customer’s balance.

curl -X POST https://api.useplinth.com/admin/suspense/susp_01JABC.../resolve \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "apply_to_invoice",
    "invoice_id": "inv_01JDEF..."
  }'

Request body

string

required

apply_to_invoice — apply to a specific invoice. credit_balance — add to the customer’s balance.

string

Required if action is apply_to_invoice.

​GET /admin/clock

​POST /admin/clock/advance

​POST /admin/tick

​GET /admin/suspense

​POST /admin/suspense/:id/resolve

GET /admin/clock

POST /admin/clock/advance

POST /admin/tick

GET /admin/suspense

POST /admin/suspense/:id/resolve