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

# Create a purchase order

A client's authorization to bill up to a set amount. Projects, invoices, and credit notes can be tied to a purchase order to track how much of it is used.


## OpenAPI

````yaml openapi.json POST /purchase-orders
openapi: 3.1.0
info:
  title: Ruddr API
  version: '1.0'
  license:
    name: Proprietary
    url: https://www.ruddr.com/master-subscription-agreement
servers:
  - url: https://www.ruddr.io/api/workspace
security:
  - bearerAuth: []
tags:
  - name: Allocations
    description: Manage resource allocations for scheduling team members to projects.
  - name: Availability Periods
    description: Manage member availability periods for capacity planning.
  - name: Business Units
    description: >-
      Manage business units for organizing invoice settings and grouping clients
      and projects.
  - name: Client Roles
    description: Manage client roles and their billing terms.
  - name: Client Tags
    description: Manage tags for categorizing clients.
  - name: Clients
    description: Manage clients and their billing settings.
  - name: Companies
    description: Manage companies in the CRM pipeline.
  - name: Company Spend Tiers
    description: Manage spend tier classifications for companies.
  - name: Company Types
    description: Manage type classifications for companies.
  - name: Contact Tags
    description: Manage tags for categorizing contacts.
  - name: Contacts
    description: Manage contacts associated with clients, companies, and opportunities.
  - name: Cost Periods
    description: Manage member cost rate periods for profitability tracking.
  - name: Credit Notes
    description: View credit notes issued against invoices.
  - name: Disciplines
    description: Manage disciplines for classifying member skill areas.
  - name: Exchange Rate
    description: Get exchange rates for multi-currency workspaces.
  - name: Exchange Rate Periods
    description: Manage custom exchange rate periods for currency conversion.
  - name: Expense Categories
    description: Manage expense categories for tracking and reporting.
  - name: Expense Items
    description: Manage individual expense line items.
  - name: Expense Receipts
    description: Download receipt files attached to expense items.
  - name: Expense Reports
    description: Manage expense reports submitted by members.
  - name: Holiday Schedules
    description: Manage holiday schedules for capacity and availability planning.
  - name: Holidays
    description: Manage individual holidays within holiday schedules.
  - name: Industries
    description: Manage industry classifications for clients and companies.
  - name: Invoice Items
    description: Manage invoice line item types for billing.
  - name: Invoices
    description: View invoices and their line items.
  - name: Job Titles
    description: Manage job title classifications for members.
  - name: Locations
    description: Manage office locations for members and projects.
  - name: Member Certifications
    description: Manage certification types that can be assigned to members.
  - name: Member Levels
    description: Manage member level classifications for career tracking.
  - name: Member Tags
    description: Manage tags for categorizing members.
  - name: Members
    description: Manage workspace members and their profiles.
  - name: Opportunities
    description: Manage sales opportunities in the CRM pipeline.
  - name: Opportunity Pipelines
    description: Manage pipelines for tracking opportunity stages.
  - name: Opportunity Lead Sources
    description: Manage lead source classifications for opportunities.
  - name: Opportunity Stages
    description: Manage pipeline stage definitions for opportunities.
  - name: Opportunity Tags
    description: Manage tags for categorizing opportunities.
  - name: Opportunity Types
    description: Manage type classifications for opportunities.
  - name: Payment Methods
    description: Manage payment method options for invoices.
  - name: Payments
    description: View payments received against invoices.
  - name: Pipeline Activities
    description: >-
      Manage pipeline activities associated with companies, contacts, members,
      and opportunities.
  - name: Pipeline Activity Types
    description: Manage activity type classifications for pipeline activities.
  - name: Practices
    description: Manage practice area classifications for organizing projects and members.
  - name: Project Billing Schedule Items
    description: Manage billing schedule items for fixed-fee project billing.
  - name: Project Budget Expenses
    description: Manage expense budget line items on projects.
  - name: Project Budget Other Items
    description: Manage other budget line items on projects.
  - name: Project Budget Product Items
    description: Manage product budget line items on projects.
  - name: Project Budget Service Items
    description: Manage additional service budget line items on projects.
  - name: Project Expenses
    description: Manage project-level expense line items.
  - name: Project Groups
    description: View project groups for organizing related projects.
  - name: Project Health Reports
    description: Manage project health status reports.
  - name: Project Members
    description: Manage team member assignments on projects.
  - name: Project Monthly Budget Expenses
    description: Manage monthly expense budget line items on projects.
  - name: Project Monthly Budget Other Items
    description: Manage monthly other budget line items on projects.
  - name: Project Monthly Budget Product Items
    description: Manage monthly product budget line items on projects.
  - name: Project Monthly Budget Service Items
    description: Manage monthly additional service budget line items on projects.
  - name: Project Other Items
    description: Manage project-level other item line items.
  - name: Project Prepayments
    description: Manage prepayments invoiced up front to offset future fees on a project.
  - name: Project Product Items
    description: Manage project-level product line items.
  - name: Project Rate Cards
    description: >-
      Manage dated rate cards holding the member and role billing rates on a
      project.
  - name: Project Revenue Adjustments
    description: Manage earned revenue adjustments for projects.
  - name: Project Revenue Recognition Entries
    description: Manage revenue recognition entries for projects.
  - name: Project Roles
    description: Manage roles defined on projects for billing and staffing.
  - name: Project Service Items
    description: Manage project-level additional service line items.
  - name: Project Tags
    description: Manage tags for categorizing projects.
  - name: Project Types
    description: Manage type classifications for projects.
  - name: Projects
    description: Manage projects and their settings.
  - name: Purchase Orders
    description: Manage client purchase orders and track the amount invoiced against them.
  - name: Resource Placeholders
    description: Manage placeholder resources for allocation planning.
  - name: Security Roles
    description: View security roles for assigning member permissions.
  - name: Skills
    description: Manage skill classifications for members and resource planning.
  - name: Task Categories
    description: Manage task category classifications for project tasks.
  - name: Task Tags
    description: Manage tags for categorizing project tasks.
  - name: Task Templates
    description: Manage reusable task templates for projects.
  - name: Tasks
    description: Manage tasks on projects for time tracking and planning.
  - name: Tax Rates
    description: Manage tax rates for invoicing.
  - name: Time Entries
    description: Manage time entries for tracking hours on projects.
  - name: Time Off Types
    description: Manage time off type classifications.
  - name: Timesheet Attestations
    description: Manage attestation statements members sign when submitting timesheets.
  - name: Timesheets
    description: Manage timesheet submissions for tracking hours across a period.
  - name: Utilization Target Periods
    description: Manage member utilization target periods for capacity planning.
  - name: Workspace Roles
    description: Manage workspace-level roles for billing rate configuration.
paths:
  /purchase-orders:
    post:
      tags:
        - Purchase Orders
      summary: Create a purchase order
      operationId: create-a-purchase-order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - number
                - name
                - amount
                - clientId
              properties:
                number:
                  type: string
                  description: >-
                    The purchase order number issued by the client (max 255
                    chars).
                name:
                  type: string
                  description: The name of the purchase order (max 255 chars).
                amount:
                  type: number
                  description: >-
                    The total amount authorized by the purchase order. Must be
                    between 0.01 and 99999999999.
                currency:
                  type: string
                  description: >-
                    The ISO 4217 currency code of the purchase order. Must be
                    the workspace currency or, when Multi-Currency is enabled,
                    one of the workspace's currencies. Defaults to the client's
                    currency when Multi-Currency is enabled, otherwise the
                    workspace currency.
                includeTax:
                  type: boolean
                  description: >-
                    Whether tax on invoices and credit notes counts toward the
                    amount used. Defaults to `true`.
                isActive:
                  type: boolean
                  description: Whether the purchase order is active. Defaults to `true`.
                start:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The start date of the purchase order. Must be in the form
                    YYYY-MM-DD and on or before `end`.
                  format: date
                end:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The end date of the purchase order. Must be in the form
                    YYYY-MM-DD and on or after `start`.
                  format: date
                notes:
                  type:
                    - string
                    - 'null'
                  description: Notes about the purchase order (max 5000 chars).
                clientId:
                  type: string
                  description: >-
                    The client ID (`uuid`) the purchase order belongs to. Cannot
                    be changed after creation.
                contactId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The contact ID (`uuid`) for the purchase order. Must be a
                    contact of the client.
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
              examples:
                Result:
                  value:
                    id: 148a7067-c17b-4a33-9ea6-8151622409ab
                    number: PO-2026-0042
                    name: Website Redesign 2026
                    amount: 50000
                    currency: USD
                    includeTax: true
                    isActive: true
                    start: '2026-01-01'
                    end: '2026-12-31'
                    notes: Approved by procurement on December 12.
                    createdAt: '2026-01-05T15:21:44.907Z'
                    client:
                      id: b46b9857-672a-47cd-a5ae-b1f3b6e5146e
                      name: Paul's Boutique
                    contact:
                      id: 72ba6b23-d29c-4138-ba46-62e2dffbe2dd
                      name: Dana Whitfield
                    amountUsed: 0
                    amountAvailable: 50000
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                Validation:
                  value:
                    status: 400
                    message: >-
                      There was a problem processing your request. See errors
                      for more details.
                    errors:
                      - '''name'' is required'
                InvalidData:
                  value:
                    status: 400
                    message: >-
                      'clientId' '7245fa47-d03f-4167-8ba5-928518a9db94' does not
                      match a valid client.
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Feature:
                  value:
                    status: 403
                    message: Feature 'Purchase Orders' is not enabled.
      deprecated: false
components:
  schemas:
    PurchaseOrder:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the object.
        number:
          type: string
          description: The purchase order number issued by the client.
        name:
          type: string
          description: The name of the purchase order.
        amount:
          type: number
          description: >-
            The total amount authorized by the purchase order, in the purchase
            order's `currency`.
        currency:
          type: string
          description: The ISO 4217 currency code of the purchase order.
        includeTax:
          type: boolean
          description: Whether tax on invoices and credit notes counts toward `amountUsed`.
        isActive:
          type: boolean
          description: >-
            Whether the purchase order is active. Only active purchase orders
            can be added to projects, invoices, and credit notes.
        start:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The start date of the purchase order. Will be in the form
            YYYY-MM-DD. `null` when the purchase order has no start date.
        end:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The end date of the purchase order. Will be in the form YYYY-MM-DD.
            `null` when the purchase order has no end date.
        notes:
          type:
            - string
            - 'null'
          description: Notes about the purchase order.
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the object was created.
        client:
          type: object
          description: The client the purchase order belongs to.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the client.
        contact:
          type:
            - object
            - 'null'
          description: The client contact associated with the purchase order.
          properties:
            id:
              type: string
              description: The unique identifier for the object.
            name:
              type: string
              description: The name of the contact.
        amountUsed:
          type: number
          description: >-
            The total of open and paid invoices on the purchase order, less open
            and applied credit notes. Excludes tax when `includeTax` is `false`.
            This is a calculated value.
        amountAvailable:
          type: number
          description: >-
            The `amount` remaining after `amountUsed` is subtracted. Negative
            when the purchase order is exceeded. This is a calculated value.
    ValidationErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: A human-readable error message.
        errors:
          type: array
          description: A list of validation error messages.
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: A human-readable error message.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key created in **Settings > API Keys**. Each key is either
        Read-Only or Full Access, chosen when the key is created. A Read-Only
        key can only make `GET` requests; `POST`, `PATCH`, and `DELETE` requests
        made with it return a `403` with the message `This API key is
        read-only.`

````

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