> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The merchant's plan, usage and entitlements

> Everything the portal gates on: active collections vs the cap, this month's sessions (and a projection) vs the quota, trial state, whether the store is frozen or erroring, the active Shopify subscription, and the plan-derived entitlements. Read-only; computed fresh on every call.



## OpenAPI

````yaml /api-reference/openapi/lite.json get /settings/subscription/status
openapi: 3.1.0
info:
  title: Search & Merchandising API
  version: 1.0.0
  description: >-
    REST API behind Depict: Search & Merchandising, the native Shopify app:
    onboarding, collections, boost & bury, dashboards, A/B testing and
    multi-store management. Endpoints are served under the /api/lite prefix and
    are authenticated with the Shopify session token that App Bridge issues to
    the embedded app.
servers:
  - url: /api/lite
security:
  - ShopifySessionToken: []
paths:
  /settings/subscription/status:
    get:
      summary: The merchant's plan, usage and entitlements
      description: >-
        Everything the portal gates on: active collections vs the cap, this
        month's sessions (and a projection) vs the quota, trial state, whether
        the store is frozen or erroring, the active Shopify subscription, and
        the plan-derived entitlements. Read-only; computed fresh on every call.
      operationId: subscriptionStatus
      parameters:
        - schema:
            type: string
            description: Lite merchant id, e.g. `shopify-<shop id>`.
          required: true
          description: Lite merchant id, e.g. `shopify-<shop id>`.
          name: merchant_id
          in: query
      responses:
        '200':
          description: The subscription status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
        '400':
          description: >-
            The query, path or body failed the schema; `detail` carries zod's
            messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '403':
          description: Authenticated, but this identity may not call the API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '404':
          description: Merchant not found for this caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
components:
  schemas:
    SubscriptionStatus:
      type: object
      properties:
        num_active_collections:
          type: integer
        max_active_collections:
          type:
            - integer
            - 'null'
        is_trial:
          type: boolean
        trial_days_left:
          type:
            - integer
            - 'null'
        proj_sessions:
          type:
            - integer
            - 'null'
          description: Sessions projected for this month; null before 4 days of data.
        num_sessions:
          type: integer
        max_sessions:
          type:
            - integer
            - 'null'
        days_until_reset:
          type: integer
        frozen:
          type: boolean
        installed_recently:
          type: boolean
        store_error:
          type:
            - string
            - 'null'
          enum:
            - invalid_api_key
            - payment_required
            - unknown
            - null
        subscription:
          anyOf:
            - $ref: '#/components/schemas/ActiveSubscriptionDTO'
            - type: 'null'
        entitlements:
          type: object
          properties:
            plan_id:
              type:
                - string
                - 'null'
              description: null = free tier.
            products:
              type: array
              items:
                type: string
                enum:
                  - search
                  - recs
                  - vm
              description: The paid products.
            size:
              type:
                - string
                - 'null'
              enum:
                - s
                - m
                - l
                - custom
                - null
            session_quota:
              type:
                - integer
                - 'null'
              description: Monthly sessions; null = unlimited or unmetered.
            max_active_collections:
              type:
                - integer
                - 'null'
            is_trial:
              type: boolean
            trial_days_left:
              type:
                - integer
                - 'null'
            features:
              type: object
              properties:
                ab_test:
                  type: boolean
                scheduled_versions:
                  type: boolean
                multi_store:
                  type: boolean
              required:
                - ab_test
                - scheduled_versions
                - multi_store
            source:
              type: string
              enum:
                - foundation
                - blobconfig
          required:
            - plan_id
            - products
            - size
            - session_quota
            - max_active_collections
            - is_trial
            - trial_days_left
            - features
            - source
          description: The plan-derived rights every portal gate reads.
      required:
        - num_active_collections
        - max_active_collections
        - is_trial
        - trial_days_left
        - proj_sessions
        - num_sessions
        - max_sessions
        - days_until_reset
        - frozen
        - installed_recently
        - store_error
        - subscription
        - entitlements
    Detail:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
      description: 'Every 4xx/5xx body: `{detail}`.'
    ActiveSubscriptionDTO:
      type: object
      properties:
        id:
          type: integer
        name:
          $ref: '#/components/schemas/SubscriptionName'
        price:
          type: string
        interval:
          $ref: '#/components/schemas/AppPricingInterval'
        billing_on:
          type:
            - string
            - 'null'
        trial_ends_on:
          type:
            - string
            - 'null'
        test:
          type: boolean
        status:
          type: string
          enum:
            - pending
            - accepted
            - active
            - declined
            - expired
            - frozen
            - cancelled
      required:
        - id
        - name
        - price
        - interval
        - billing_on
        - trial_ends_on
        - test
        - status
      description: The active Shopify app subscription, if any.
    SubscriptionName:
      type: string
      enum:
        - Basic
        - Essential
        - Pro
        - Custom
    AppPricingInterval:
      type: string
      enum:
        - EVERY_30_DAYS
        - ANNUAL
  securitySchemes:
    ShopifySessionToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Shopify App Bridge session token of the embedded Depict: Search &
        Merchandising app. The shop in the token determines the merchant;
        merchant_id parameters must belong to that shop.

````