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

# Get Customer Paywall Status

> Returns whether a specific customer currently has an unrecovered past-due payment, and the total amount owed.

Use this to power an in-app prompt that asks a past-due customer to update their payment method. The bundled `revtain-paywall.js` snippet calls this endpoint for you; you can also call it directly.

**Authentication:** this endpoint accepts your **publishable key** (`rev_pk_...`) in the `X-API-KEY` header, so it is safe to call from client-side code. Your secret API key also works for server-side calls.




## OpenAPI

````yaml /api-reference/openapi.yaml get /api/recovery/paywall-status
openapi: 3.0.3
info:
  title: Revtain API
  description: >
    Recover failed payments. No checkout changes. Works with your existing
    payment stack.


    ## Choose Your Path


    **Using Chargebee, Recurly, Stripe Billing, Braintree, Zuora, or Shopify
    (ReCharge)?**

    Use a Connector — paste one webhook URL, no code, 5 minutes.


    **Custom billing system or want full API control?**

    Use the Recovery Engine directly. The quickstart gets you to a working
    recovery call in 60 seconds.


    ## Authentication


    Pass your API key via the `X-API-KEY` header on all requests:


    ```

    X-API-KEY: rev_dTviCg52T8gLPCjrrW4KA0NKf_f5pQgk

    ```


    Keep this secret. Your API key can trigger charges. Never expose it in
    client-side code, public repos, or logs.


    ## Base URL


    ```

    https://api.revtain.com

    ```


    Same URL for testing and production. Test mode is controlled by your gateway
    type — onboard with a test gateway (e.g., Stripe `sk_test_...`) for sandbox,
    live key for production.
  version: 1.0.0
  contact:
    email: support@revtain.com
servers:
  - url: https://api.revtain.com
    description: Production & Sandbox (test mode controlled by gateway key)
security:
  - ApiKeyAuth: []
tags:
  - name: Recovery Engine
    description: Trigger and track payment recovery attempts
  - name: Predictive Risk Engine
    description: Pre-screen payments before they fail
  - name: Retention
    description: Hosted cancel flow to reduce voluntary churn
  - name: Health
    description: Service health check
paths:
  /api/recovery/paywall-status:
    get:
      tags:
        - Recovery Engine
      summary: Get Customer Paywall Status
      description: >
        Returns whether a specific customer currently has an unrecovered
        past-due payment, and the total amount owed.


        Use this to power an in-app prompt that asks a past-due customer to
        update their payment method. The bundled `revtain-paywall.js` snippet
        calls this endpoint for you; you can also call it directly.


        **Authentication:** this endpoint accepts your **publishable key**
        (`rev_pk_...`) in the `X-API-KEY` header, so it is safe to call from
        client-side code. Your secret API key also works for server-side calls.
      operationId: getPaywallStatus
      parameters:
        - name: customerEmail
          in: query
          required: true
          description: >-
            The customer's email address — the same value passed as
            `customerEmail` on `/api/recovery/execute`.
          schema:
            type: string
            format: email
          example: customer@example.com
      responses:
        '200':
          description: Paywall status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaywallStatusResponse'
              examples:
                past_due:
                  summary: Customer is past due
                  value:
                    isPastDue: true
                    totalOwedCents: 4900
                    currency: USD
                    failedPaymentCount: 1
                    oldestFailureAt: '2026-05-14T09:12:00.000Z'
                clear:
                  summary: Customer is in good standing
                  value:
                    isPastDue: false
                    totalOwedCents: 0
                    currency: USD
                    failedPaymentCount: 0
                    oldestFailureAt: null
        '400':
          description: Missing customer identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  schemas:
    PaywallStatusResponse:
      type: object
      properties:
        isPastDue:
          type: boolean
          description: >-
            Whether the customer currently has one or more unrecovered failed
            payments.
          example: true
        totalOwedCents:
          type: integer
          description: >-
            Total outstanding across all unrecovered failed payments, in the
            smallest currency unit.
          example: 4900
        currency:
          type: string
          example: USD
        failedPaymentCount:
          type: integer
          description: Number of unrecovered failed payments for this customer.
          example: 1
        oldestFailureAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp of the oldest unrecovered failure. Null when the customer
            is not past due.
          example: '2026-05-14T09:12:00.000Z'
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed.
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            paymentMethodToken:
              - Payment method token is required
            amount:
              - Amount must be a positive number
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized. Missing or invalid API key.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: 'Your Revtain API key (format: `rev_xxx`). Provided during onboarding.'

````