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

# Create a recovery case

> Enrol a customer’s past-due invoices in recovery.



## OpenAPI

````yaml openapi-billing.json POST /v1/recovery_cases
openapi: 3.1.0
info:
  title: Yorlet Billing API
  description: APIs for managing invoices, coupons, credit grants, and subscription items.
  version: 1.0.0
servers:
  - url: https://api.yorlet.com
    description: Production
  - url: https://api.yorlet.io
    description: Sandbox
security: []
paths:
  /v1/recovery_cases:
    post:
      tags:
        - Recovery Cases
      summary: Create a recovery case
      description: Enrol a customer’s past-due invoices in recovery.
      operationId: recovery_cases_create
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                invoices:
                  type: array
                  items:
                    type: string
                    pattern: ^[a-zA-Z0-9_]+$
                  minItems: 1
                  description: >-
                    The IDs of the invoices to enrol. Every invoice must be
                    open, belong to the same customer and be more than 28 days
                    past due.
                metadata:
                  type:
                    - object
                    - 'null'
                  additionalProperties:
                    type: string
                  description: The metadata for the case.
              required:
                - invoices
      responses:
        '200':
          description: Returns a recovery case object if successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the object.
                  created:
                    type: number
                    description: >-
                      Time at which the object was created. Measured in seconds
                      since the Unix epoch.
                  account:
                    type: string
                    description: >-
                      The account that the object belongs to. Only returned if
                      the request is made with a valid Yorlet-Context header.
                  deleted:
                    type: boolean
                    default: false
                    description: Only returned if the object has been deleted.
                  object:
                    type: string
                    enum:
                      - recovery_case
                  amount_enrolled:
                    type: integer
                    default: 0
                    description: >-
                      The total amount outstanding across the enrolled invoices
                      when the case was opened.
                  amount_recovered:
                    type: integer
                    default: 0
                    description: >-
                      The amount collected against the enrolled invoices since
                      the case was opened.
                  canceled_at:
                    type:
                      - integer
                      - 'null'
                    description: The date and time the case was canceled.
                  currency:
                    type: string
                    enum:
                      - gbp
                      - usd
                      - eur
                      - sek
                    description: >-
                      Three-letter ISO currency code, in lowercase. Must be a
                      supported currency.
                    example: gbp
                  customer:
                    anyOf:
                      - type: string
                      - type: object
                        additionalProperties: {}
                    description: The customer the case is recovering from.
                  email_attempt:
                    type: integer
                    default: 0
                    description: The number of escalated recovery emails sent for the case.
                  enrolled_at:
                    type:
                      - integer
                      - 'null'
                    description: The date and time the invoices were enrolled in recovery.
                  enrolled_by:
                    type:
                      - string
                      - 'null'
                    description: >-
                      The ID of the user who enrolled the case, if it was
                      enrolled from the dashboard.
                  fee_collected:
                    type: integer
                    default: 0
                    description: >-
                      The total recovery fee charged against the amount
                      recovered, including tax.
                  fee_percent:
                    type: number
                    description: >-
                      The percentage of each recovered payment charged as a
                      recovery fee.
                  hosted_recovery_url:
                    type:
                      - string
                      - 'null'
                    description: >-
                      The URL of the hosted recovery page, where the customer
                      can pay or set up a payment plan.
                  invoices:
                    type: array
                    items:
                      type: string
                    default: []
                    description: The IDs of the invoices enrolled in the case.
                  last_contacted_at:
                    type:
                      - integer
                      - 'null'
                    description: >-
                      The date and time the customer was last contacted about
                      the case.
                  metadata:
                    type:
                      - object
                      - 'null'
                    additionalProperties:
                      type: string
                    description: >-
                      Set of key-value pairs that you can attach to an object.
                      This can be useful for storing additional information
                      about the object in a structured format.
                  payment_plan:
                    anyOf:
                      - type: string
                      - type: object
                        additionalProperties: {}
                      - type: 'null'
                    description: >-
                      The active payment plan for the case, if the customer has
                      accepted one.
                  recovered_at:
                    type:
                      - integer
                      - 'null'
                    description: The date and time every enrolled invoice was fully paid.
                  status:
                    type: string
                    enum:
                      - open
                      - plan_active
                      - recovered
                      - canceled
                    description: The status of the case.
                required:
                  - id
                  - created
                  - object
                  - canceled_at
                  - currency
                  - customer
                  - enrolled_at
                  - enrolled_by
                  - fee_percent
                  - hosted_recovery_url
                  - last_contacted_at
                  - payment_plan
                  - recovered_at
                  - status
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API Key authentication. Use "Bearer YOUR_API_KEY".

````