invoiceninja/openapi/paths/recurring_invoices.yaml

  /api/v1/recurring_invoices:
    get:
      tags:
        - Recurring Invoices
      summary: "List recurring invoices"
      description: |
        Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.          

      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 
      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: "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"
      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"