/api/v1/recurring_invoices:
    get:
      tags:
        - Recurring Invoices
      summary: "List recurring invoices"
      description: |
        ## GET /api/v1/recurring_invoices

        Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.  
      x-codeSamples:
      - lang: php
        label: php
        source: |
          $ninja = new InvoiceNinja("your_token");
          $invoices = $ninja->recurring_invoices->all([
            'per_page' => 10,
            'page' => 1,
            'sort' => 'number|asc'
          ]);
      - lang: curl
        label: curl
        source: |
          curl --request GET \
            --url 'https://invoicing.co/api/v1/recurring_invoices?per_page=10&page=1&sort=number&sort_dir=asc' \
            --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
            --header 'Accept: application/json'
      operationId: getRecurringInvoices
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/client_id"
        - $ref: "#/components/parameters/created_at"
        - $ref: "#/components/parameters/updated_at"
        - $ref: "#/components/parameters/is_deleted"
        - $ref: "#/components/parameters/filter_deleted_clients"
        - $ref: "#/components/parameters/vendor_id"
        - name: filter
          in: query
          description: |
            Searches across a range of columns including:  
            - custom_value1  
            - custom_value2  
            - custom_value3  
            - custom_value4
          required: false
          schema:
            type: string
          example: ?filter=bob
        - name: client_status
          in: query
          description: |
            A comma separated list of invoice status strings. Valid options include:  
            - all
            - active  
            - paused  
            - completed  
          required: false
          schema:
            type: string
          example: ?client_status=active,paused
        - name: sort
          in: query
          description: Returns the list sorted by column in ascending or descending order.
          required: false
          schema:
            type: string
          example: id|desc number|desc balance|asc 
        - name: number
          in: query
          description: |
            Filters the list by number.
          required: false
          schema:
            type: string
          example: ?number=123
        - name: product_key
          in: query
          description: |
            Filters the list by product_key.
          required: false
          schema:
            type: string
          example: ?product_key=123
        - name: next_send_between
          in: query
          description: |
            Filters the list by next_send_between.
          required: false
          schema:
            type: string
          example: ?next_send_between=2025-01-01|2025-01-31
        - name: frequency_id
          in: query
          description: |
            Filters the list by frequency_id.
          required: false
          schema:
            type: string
          example: ?frequency_id=1,2,3
      responses:
        200:
          description: "A list of recurring_invoices"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:  
                type: object
                properties:
                  data: 
                    type: array
                    items:
                      $ref: '#/components/schemas/RecurringInvoice'
                  meta:
                    type: object
                    $ref: '#/components/schemas/Meta'
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
    post:
      tags:
        - Recurring Invoices
      summary: "Create recurring invoice"
      description: |
        ## POST /api/v1/recurring_invoices

        Adds a Recurring Invoice to the system
      operationId: storeRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
      x-codeSamples:
      - lang: php
        label: php
        source: |
          $ninja = new InvoiceNinja("your_token");
          $invoices = $ninja->recurring_invoices->create([
            'client_id' => 'AxP7K9nY5z',
            'date' => '2022-01-01',
            'due_date' => '2022-01-31',
            'private_notes' => 'super secret',
            'public_notes' => 'public notes',
            'custom_value1' => 'custom value 1',
            'custom_value2' => 'custom value 2',
            'line_items' => [
              [
                    'quantity' => 1,
                    'cost' => 14,
                    'product_key' => 'sku_4_u',
                    'notes' => 'The actual product description',
                    'discount' => 0,
                    'is_amount_discount' => true,
                    'tax_name1' => '',
                    'tax_rate1' => 0,
                    'tax_name2' => '',
                    'tax_rate2' => 0,
                    'tax_name3' => '',
                    'tax_rate3' => 0,
                    'sort_id' => '0',
                    'custom_value1' => 'https://picsum.photos/200',
                    'custom_value2' => '94',
                    'custom_value3' => 'Alias vel eveniet.',
                    'custom_value4' => 'Iusto aut quis qui.',
                    'type_id' => '1',
                    'tax_id' => '1'
              ]
            ]
          ]);
      - lang: curl
        label: curl
        source: |
          curl --request POST \
            --url 'https://invoicing.co/api/v1/recurring_invoices' \
            --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
            --header 'Accept: application/json' \
            --header 'Content-Type: application/json' \
            --data '{
              "client_id": "AxP7K9nY5z",
              "date": "2022-01-01",
              "due_date": "2022-01-31",
              "private_notes": "super secret",
              "public_notes": "public notes",
              "custom_value1": "custom value 1",
              "custom_value2": "custom value 2",
              "line_items": [
                {
                  "quantity": 1,
                  "cost": 14,
                  "product_key": "sku_4_u",
                  "notes": "The actual product description",
                  "discount": 0,
                  "is_amount_discount": true,
                  "tax_name1": "",
                  "tax_rate1": 0,
                  "tax_name2": "",
                  "tax_rate2": 0,
                  "tax_name3": "",
                  "tax_rate3": 0,
                  "sort_id": "0",
                  "custom_value1": "https://picsum.photos/200",
                  "custom_value2": "94",
                  "custom_value3": "Alias vel eveniet.",
                  "custom_value4": "Iusto aut quis qui.",
                  "type_id": "1",
                  "tax_id": "1"
                }
              ]
            }'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecurringInvoiceRequest"
      responses:
        200:
          description: "Returns the saved RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  
  "/api/v1/recurring_invoices/{id}":
    get:
      tags:
        - Recurring Invoices
      summary: "Show recurring invoice"
      description: "Displays an RecurringInvoice by id"
      operationId: showRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The RecurringInvoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
    put:
      tags:
        - Recurring Invoices
      summary: "Update recurring invoice"
      description: "Handles the updating of an RecurringInvoice by id"
      operationId: updateRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The RecurringInvoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
    delete:
      tags:
        - Recurring Invoices
      summary: "Delete recurring invoice"
      description: "Handles the deletion of an RecurringInvoice by id"
      operationId: deleteRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The RecurringInvoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns a HTTP status"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  "/api/v1/recurring_invoices/{id}/edit":
    get:
      tags:
        - Recurring Invoices
      summary: "Edit recurring invoice"
      description: "Displays an RecurringInvoice by id"
      operationId: editRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The RecurringInvoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  
  /api/v1/recurring_invoices/create:
    get:
      tags:
        - Recurring Invoices
      summary: "Blank recurring invoice"
      description: "Returns a blank object with default values"
      operationId: getRecurringInvoicesCreate
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
      responses:
        200:
          description: "A blank RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  /api/v1/recurring_invoices/bulk:
    post:
      tags:
        - Recurring Invoices
      summary: "Bulk recurring invoice actions"
      description: |
        There are multiple actions that are available including:

      operationId: bulkRecurringInvoices
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/index"
      requestBody:
        description: "Bulk action details"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: |
                    The action to be performed, options include:  
                    - `start`  
                      Starts (or restarts) the recurring invoice. **note** if the recurring invoice has been stopped for a long time, it will attempt to catch back up firing a new Invoice every hour per interval that has been missed.  
                      If you do not wish to have the recurring invoice catch up, you should set the next_send_date to the correct date you wish the recurring invoice to commence from.
                    - `stop`  
                      Stops the recurring invoice. 
                    - `send_now`  
                      Force sends the recurring invoice - this option is only available when the recurring invoice is in a draft state.  
                    - `restore`  
                      Restores the recurring invoice from an archived or deleted state.
                    - `archive`  
                      Archives the recurring invoice. The recurring invoice will not fire in this state.
                    - `delete`  
                      Deletes a recurring invoice.  
                ids:
                  type: array
                  items:
                    description: "Array of hashed IDs to be bulk 'actioned - ['D2J234DFA','D2J234DFA','D2J234DFA']"
                    type: string
              example:
                action: start
                ids: ['D2J234DFA','D2J234DFA','D2J234DFA']
      responses:
        200:
          description: "The RecurringInvoice response"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  "/api/v1/recurring_invoices/{id}/{action}":
    get:
      deprecated: true
      tags:
        - Recurring Invoices
      summary: "Custom recurring invoice action"
      description: "Performs a custom action on an RecurringInvoice.\n\n    The current range of actions are as follows\n    - clone_to_RecurringInvoice\n    - clone_to_quote\n    - history\n    - delivery_note\n    - mark_paid\n    - download\n    - archive\n    - delete\n    - email"
      operationId: actionRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The RecurringInvoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
        - name: action
          in: path
          description: "The action string to be performed"
          required: true
          schema:
            type: string
            format: string
          example: clone_to_quote
      responses:
        200:
          description: "Returns the RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  "/api/v1/recurring_invoice/{invitation_key}/download":
    get:
      tags:
        - Recurring Invoices
      summary: "Download recurring invoice PDF"
      description: "Downloads a specific invoice"
      operationId: downloadRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: invitation_key
          in: path
          description: "The Recurring Invoice Invitation Key"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the recurring invoice pdf"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"
  "/api/v1/recurring_invoices/{id}/upload":
    post:
      tags:
        - Recurring Invoices
      summary: "Add recurring invoice document"
      description: "Handles the uploading of a document to a recurring_invoice"
      operationId: uploadRecurringInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The RecurringInvoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      requestBody:
        description: "File Upload Body"
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                _method:
                  type: string
                  example: PUT
                documents:
                  type: array
                  items:
                    description: "Array of binary documents for upload"
                    type: string
                    format: binary
      responses:
        200:
          description: "Returns the RecurringInvoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecurringInvoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: '#/components/responses/422'
        429:
          $ref: '#/components/responses/429'
        5XX:
          description: 'Server error'
        default:
          $ref: "#/components/responses/default"