---
title: "Sync Subscription Status"
method: POST
path: "/api/v1/subscriptions/sync"
tags: ["Subscriptions", "Subscriptions"]
---

# Sync Subscription Status

`POST /api/v1/subscriptions/sync`

## Request

- Base URL: `https://api.gemstoneaiapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemstoneaiapp.com/api/v1/subscriptions/sync`
- Auth: HTTP bearer

Sync subscription status with RevenueCat.

Call this on app launch to ensure local DB matches RevenueCat state.
Useful if webhooks were missed or for initial sync.

**When to call:**
- App launch/foreground
- After completing a purchase in the app
- When subscription status seems stale

**Returns:**
Quick subscription status with updated data from RevenueCat.

## Response `200`

Successful Response

- QuickSubscriptionStatusResponse: Quick subscription status check - lightweight response for UI state management. Use this API when you need to quickly check: - Is user Free or Premium? - Is subscription active? - How many scans/gems remaining? Perfect for: Headers, dashboards, quick checks before actions
  - `plan_type` string, required: 'free' or 'premium'
  - `is_active` boolean, required: Is subscription active?
  - `is_premium` boolean, required: True if user has active premium subscription, False otherwise
  - `scans_remaining` union, required: 'unlimited' or number
    - string
    - integer
  - `collection_slots_remaining` union, required: 'unlimited' or number (10 - current_count)
    - string
    - integer
  - `scans_limit` integer, nullable: Monthly scan limit (null if unlimited)
  - `collection_limit` integer, nullable: Collection size limit (null if unlimited)
  - `scan_tier` ScanTierQuota: Monthly allowance of a capped paid tier (LNK-SCANTIERS). Null on free plans and on unlimited (pre-tier) Premium.
    - `tier` string, required
    - `scans_used` integer, required
    - `scans_limit` integer, required
    - `scans_remaining` integer, required
    - `resets_at` string, required
    - `upgrade_tier` string, nullable

---

[API](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api.md) · [All operations](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/revisions/fcb441f55161?raw)