---
title: "Refresh subscription from the provider (post-checkout fast plan update)"
method: POST
path: "/api/v2/billing/refresh"
tags: ["v2 Billing"]
---

# Refresh subscription from the provider (post-checkout fast plan update)

`POST /api/v2/billing/refresh`

## Request

- Base URL: `https://pdf2md.dev`
- URL: `https://pdf2md.dev/api/v2/billing/refresh`
- Auth: one of:
  - API key in cookie `p2m_session`
  - HTTP bearer

EP-039-T6. Pulls the provider's CURRENT subscription state server-side (GET /paywall/{id}/user, x-api-key only) and reconciles our DB, then returns the (possibly just-updated) effective plan — so the web app / extension flip to the paid tier immediately after a checkout-success redirect instead of waiting for the webhook. Webhooks remain the source of truth; this only fills gaps (a webhook the provider gave up retrying) and confirms fast. Reachable by a web session OR a device-signed linked device (AccountAuthMiddleware); identity for the read is the account email (or stored monetize_customer_id). Best-effort: a provider read error still returns the stored state. The read never leaves api-facade.

## Response `200`

Effective plan after reconcile

- object
  - `tier` string, required: Effective tier after the provider read (free|builder|pro|business|...)
  - `refreshed` boolean, required: true when the read changed our stored subscription state
  - `subscription` object, nullable
    - `status` string
    - `cancel_at_period_end` boolean
    - `current_period_end` string, date-time, nullable
    - `trial_end` string, date-time, nullable
    - `lifetime` boolean: EP-069-T13: a live one-time unlock is held.
    - `manageable` boolean: EP-070-T5: false when the only purchase is the unlock (nothing to cancel).

## Other responses

- `401`: Missing/invalid API key or session
- `503`: Billing not configured

---

[API](https://skmtc.dev/pdf2md/apis/pdf-to-markdown-api-facade.md) · [All operations](https://skmtc.dev/pdf2md/apis/pdf-to-markdown-api-facade/llms.txt) · [OpenAPI document](https://skmtc.dev/pdf2md/apis/pdf-to-markdown-api-facade/revisions/4636782fb8b6?raw)