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

# Change an invoice status

> Moves an invoice to another status. Refunded and voided invoices can no longer change.
Setting `paid` records a payment for the full amount.
If the workspace requires a reason for voiding or cancelling, include `reason_code`.
Requires the `documents:write` scope.




## OpenAPI

````yaml /openapi.yaml put /invoices/{id}/status
openapi: 3.1.0
info:
  title: BeanRails Public API
  version: 1.0.0
  description: >
    Read and write BeanRails contacts, works, invoices, quotations and invoice
    payments from your own systems.

    Authenticate every request with an API key. See the guides for scopes,
    pagination and error handling.
servers:
  - url: https://{host}/api/public/v1
    description: Public API v1
    variables:
      host:
        default: app.beanrails.com
        description: The host your BeanRails workspace is served from.
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Customers and leads.
  - name: Contact addresses
    description: Billing, shipping and service addresses of a contact.
  - name: Works
    description: Service or delivery jobs.
  - name: Work PODs
    description: Proof of delivery records submitted by drivers (read only).
  - name: Invoices
    description: Invoices, including status changes.
  - name: Quotations
    description: Quotations, including status changes.
  - name: Invoice payments
    description: Payments recorded against an invoice.
paths:
  /invoices/{id}/status:
    parameters:
      - $ref: '#/components/parameters/Id'
    put:
      tags:
        - Invoices
      summary: Change an invoice status
      description: >
        Moves an invoice to another status. Refunded and voided invoices can no
        longer change.

        Setting `paid` records a payment for the full amount.

        If the workspace requires a reason for voiding or cancelling, include
        `reason_code`.

        Requires the `documents:write` scope.
      operationId: updateInvoiceStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusInput'
            example:
              status: unpaid
      responses:
        '200':
          description: The updated invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The record ID.
      schema:
        type: integer
  schemas:
    StatusInput:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: A status value valid for this document type.
        reason_code:
          type: string
          description: >-
            A reason code from the workspace. Required when voiding or
            cancelling if the workspace enforces reasons.
    DocumentEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Document'
    Document:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        document_type:
          type: string
          enum:
            - invoice
            - quotation
        document_number:
          type: string
        document_date:
          type: string
        document_due_date:
          type:
            - string
            - 'null'
        status:
          type: string
          description: >
            Invoices: `draft`, `unpaid`, `partially_paid`, `paid`, `voided`,
            `refunded`.

            Quotations: `draft`, `pending`, `invoiced`, `completed`,
            `cancelled`.

            Workspaces can rename and add statuses.
        status_name:
          type:
            - string
            - 'null'
        currency:
          type: string
          description: Three letter currency code.
        contact:
          oneOf:
            - $ref: '#/components/schemas/Contact'
            - type: 'null'
        sub_total:
          type: number
        total_discount:
          type: number
        total_tax:
          type: number
        total_amount:
          type: number
        final_amount:
          type: number
          description: The amount due after adjustments.
        amount_paid:
          type: number
        remaining_amount:
          type: number
        pdf_url:
          type:
            - string
            - 'null'
        remarks:
          type:
            - string
            - 'null'
        items:
          type: array
          description: Only on the retrieve endpoints.
          items:
            type: object
            additionalProperties: true
        taxes:
          type: array
          description: Only on the retrieve endpoints.
          items:
            type: object
            additionalProperties: true
        discounts:
          type: array
          description: Only on the retrieve endpoints.
          items:
            type: object
            additionalProperties: true
        addresses:
          type: object
          description: Only on the retrieve endpoints.
          properties:
            billing:
              type:
                - object
                - 'null'
              additionalProperties: true
            shipping:
              type:
                - object
                - 'null'
              additionalProperties: true
        created_at:
          type: string
        updated_at:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: A stable, machine readable code.
              examples:
                - not_found
            message:
              type: string
              description: A human readable explanation.
    ValidationError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - fields
          properties:
            code:
              type: string
              enum:
                - validation_failed
            message:
              type: string
            fields:
              type: object
              description: Field names mapped to a list of messages.
              additionalProperties:
                type: array
                items:
                  type: string
    Contact:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        contact_number:
          type: string
        company_name:
          type:
            - string
            - 'null'
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
        lifecycle_stage:
          type: string
          enum:
            - lead
            - customer
        status:
          type:
            - string
            - 'null'
        status_name:
          type:
            - string
            - 'null'
        user:
          type:
            - object
            - 'null'
          description: The assigned user.
          properties:
            id:
              type: integer
            name:
              type: string
            email:
              type: string
        groups:
          type: array
          items:
            type: object
            additionalProperties: true
        primary_address:
          oneOf:
            - $ref: '#/components/schemas/ContactAddress'
            - type: 'null'
        works_count:
          type:
            - integer
            - 'null'
        quotations_count:
          type:
            - integer
            - 'null'
        invoices_count:
          type:
            - integer
            - 'null'
        created_at:
          type: string
        updated_at:
          type: string
    ContactAddress:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        name:
          type: string
        attention:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        company_name:
          type:
            - string
            - 'null'
        mobile_no:
          type:
            - string
            - 'null'
        office_no:
          type:
            - string
            - 'null'
        address1:
          type:
            - string
            - 'null'
        address2:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        postcode:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
          description: Two letter country code.
        country_name:
          type:
            - string
            - 'null'
        zone_id:
          type:
            - integer
            - 'null'
        is_primary:
          type: boolean
  responses:
    Unauthorized:
      description: The API key is missing, invalid, revoked or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_api_key
              message: The API key is invalid, revoked, or expired.
    Forbidden:
      description: >-
        The key lacks the required scope, the key owner's role no longer allows
        it, or the owner's account is suspended.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: insufficient_scope
              message: This API key does not have the required scope.
    NotFound:
      description: The record does not exist, or your key is not allowed to see it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: The requested resource was not found.
    ValidationFailed:
      description: >-
        The request body failed validation. `error.fields` lists the problems
        per field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            error:
              code: validation_failed
              message: The attention field is required.
              fields:
                attention:
                  - The attention field is required.
    RateLimited:
      description: >-
        You exceeded the key's requests per minute. Wait for the number of
        seconds in the `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds until you can retry.
          schema:
            type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key created in BeanRails, for example `brk_live_...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.