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

# Get My Subscription

> Get the current user's active Stripe subscription for the project

Retrieve the current authenticated user's active subscription for the project. Use this to display subscription status in your application.

## Authentication

<Note>
  This endpoint requires end user authentication via HTTP Bearer Token with project scope.
</Note>

## Query Parameters

<ParamField query="test_mode" type="boolean" default="true">
  Use test mode data. Set to `false` for production subscriptions.
</ParamField>

## Response

Returns the subscription object if active, or `null` if no subscription exists.

<ResponseField name="id" type="string (UUID)">
  Internal subscription record ID
</ResponseField>

<ResponseField name="project_id" type="string (UUID)">
  Project the subscription belongs to
</ResponseField>

<ResponseField name="user_id" type="string (UUID)">
  User who owns the subscription
</ResponseField>

<ResponseField name="is_test_mode" type="boolean">
  Whether this is a test mode subscription
</ResponseField>

<ResponseField name="subscription_id" type="string">
  Stripe subscription ID (e.g., `sub_ABC123`)
</ResponseField>

<ResponseField name="customer_id" type="string">
  Stripe customer ID
</ResponseField>

<ResponseField name="status" type="string">
  Subscription status: `active`, `trialing`, `past_due`, `canceled`, `incomplete`
</ResponseField>

<ResponseField name="plan_name" type="string">
  Name of the subscribed plan
</ResponseField>

<ResponseField name="quantity" type="integer">
  Number of subscription seats/units
</ResponseField>

<ResponseField name="current_period_start" type="datetime">
  Start of current billing period
</ResponseField>

<ResponseField name="current_period_end" type="datetime">
  End of current billing period (renewal date)
</ResponseField>

<ResponseField name="cancel_at" type="datetime">
  Scheduled cancellation date (if set)
</ResponseField>

<ResponseField name="cancelled_at" type="datetime">
  When cancellation was requested
</ResponseField>

<ResponseField name="created_at" type="datetime">
  When subscription was created
</ResponseField>

## Example Request

```bash theme={null}
curl -X GET "https://api.devkit4ai.com/api/v1/payments/stripe/my-subscription?test_mode=true" \
  -H "Authorization: Bearer {end_user_jwt}"
```

## Example Response

### Active Subscription

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440000",
  "user_id": "770e8400-e29b-41d4-a716-446655440000",
  "is_test_mode": true,
  "subscription_id": "sub_1ABC123def456",
  "customer_id": "cus_XYZ789",
  "status": "active",
  "plan_name": "Pro Plan",
  "quantity": 1,
  "current_period_start": "2026-01-01T00:00:00Z",
  "current_period_end": "2026-02-01T00:00:00Z",
  "cancel_at": null,
  "cancelled_at": null,
  "created_at": "2025-12-15T10:30:00Z"
}
```

### No Subscription

```json theme={null}
null
```

## Subscription Status Flow

```mermaid theme={null}
stateDiagram-v2
    [*] --> incomplete: Checkout started
    incomplete --> active: Payment successful
    incomplete --> [*]: Payment failed
    active --> trialing: Trial period
    trialing --> active: Trial ended
    active --> past_due: Payment failed
    past_due --> active: Payment recovered
    past_due --> canceled: Grace period expired
    active --> canceled: User cancels
    canceled --> [*]
```

## Integration Example

```typescript theme={null}
// React hook for subscription status
import { useQuery } from '@tanstack/react-query';

export function useSubscription() {
  return useQuery({
    queryKey: ['subscription'],
    queryFn: async () => {
      const response = await fetch('/api/subscription');
      if (!response.ok) throw new Error('Failed to fetch subscription');
      return response.json();
    }
  });
}

// Usage in component
function SubscriptionBadge() {
  const { data: subscription, isLoading } = useSubscription();
  
  if (isLoading) return <Spinner />;
  if (!subscription) return <Badge>Free</Badge>;
  
  return <Badge variant={subscription.status}>{subscription.plan_name}</Badge>;
}
```

## Common Use Cases

| Use Case                | Implementation                    |
| ----------------------- | --------------------------------- |
| Show upgrade button     | Check if `subscription` is `null` |
| Display plan name       | Use `subscription.plan_name`      |
| Show renewal date       | Format `current_period_end`       |
| Warn about cancellation | Check if `cancel_at` is set       |
| Handle payment issues   | Check for `past_due` status       |

## Error Responses

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| `401`  | Unauthorized - Invalid or missing authentication |
| `404`  | Project not found or Stripe not configured       |

## Related Pages

<CardGroup cols={2}>
  <Card title="Create Checkout" icon="credit-card" href="/cloud-api/payments/stripe/create-checkout-session">
    Start a new subscription
  </Card>

  <Card title="Cancel Subscription" icon="xmark" href="/cloud-api/payments/stripe/cancel-subscription">
    Cancel user's subscription
  </Card>

  <Card title="Update Subscription" icon="arrows-rotate" href="/cloud-api/payments/stripe/update-subscription">
    Change subscription plan
  </Card>

  <Card title="Customer Portal" icon="user-gear" href="/cloud-api/payments/stripe/create-customer-portal">
    Let user manage billing
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /api/v1/payments/stripe/my-subscription
openapi: 3.1.0
info:
  title: Dev Kit for AI API
  description: 'API for Dev Kit for AI: Developer Toolkit for AI-Powered Web Applications'
  version: 1.6.1
servers:
  - url: https://api.devkit4ai.com
    description: Dev Kit for AI Production Server
  - url: https://api.vibecoding.ad
    description: Vibe Coding Production Server
security: []
paths:
  /api/v1/payments/stripe/my-subscription:
    get:
      tags:
        - Stripe Subscriptions
      summary: Get My Subscription
      description: Get the current user's active Stripe subscription for the project.
      operationId: get_my_subscription_api_v1_payments_stripe_my_subscription_get
      parameters:
        - name: test_mode
          in: query
          required: false
          schema:
            type: boolean
            description: Use test mode
            default: true
            title: Test Mode
          description: Use test mode
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/StripeSubscriptionResponse'
                  - type: 'null'
                title: >-
                  Response Get My Subscription Api V1 Payments Stripe My
                  Subscription Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    StripeSubscriptionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        project_id:
          type: string
          format: uuid
          title: Project Id
        user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: User Id
        is_test_mode:
          type: boolean
          title: Is Test Mode
        subscription_id:
          type: string
          title: Subscription Id
        customer_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Id
        status:
          type: string
          title: Status
        plan_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Plan Name
        quantity:
          type: integer
          title: Quantity
        current_period_start:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Current Period Start
        current_period_end:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Current Period End
        cancel_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cancel At
        cancelled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cancelled At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - project_id
        - is_test_mode
        - subscription_id
        - status
        - quantity
        - created_at
      title: StripeSubscriptionResponse
      description: Stripe subscription details.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````