> ## Documentation Index > Fetch the complete documentation index at: https://developer.tyms.io/llms.txt > Use this file to discover all available pages before exploring further. # Create purchase order (manual or AI) > Create a buying commitment to a vendor. Supports AI create when `prompt` is present. Use `/purchase-orders/{uuid}/convert-to-restock` when goods arrive. ## OpenAPI ````yaml /openapi/adam-v1.json post /purchase-orders openapi: 3.0.3 info: title: Tyms Developer API version: 1.0.0 description: >- REST API for Tyms — the AI-Native Accounting Platform for small and medium-sized businesses across service, consulting, retail, and manufacturing. Paths are appended to the server URL. **Business key** (`tyms_sk_...`): all routes except partner distributor routes and OAuth authorization steps that document their own auth. **Partner key** (`adam_partner_sk_...` or equivalent): `POST /register-business`, `GET /referred-businesses`, billing status, and seat/credit grants on referred businesses. **OAuth**: integration apps use `tyms_pk_...` / `tyms_sk_...` plus user Bearer tokens — see the OAuth guide. Financial reports match what you see in the Tyms app. AI create endpoints accept optional attachment objects (`name`, `file`, `type`) — see the Attachments page in this docs site. servers: - url: https://staging-api.tyms.io/v1/adam description: Sandbox (pre-production). Request credentials at developer@tyms.io. - url: https://api.tyms.io/v1/adam description: Production security: - apiKey: [] tags: - name: Partners description: >- Referral partner (distributor) flows — partner API key only. Register businesses, list referrals, read billing, and grant Plus seats or AI credits from partner holding. - name: Authentication description: Validate a business Developer API key. - name: OAuth description: >- Third-party integration authorization — connect Tyms users to your app without sharing their business secret keys. - name: Chart of accounts description: COA and bank-linked accounts. - name: Invoices description: Invoice CRUD and payments. - name: Bills description: Bill CRUD and payments. - name: Expenses description: Expense CRUD. - name: Income description: Income record CRUD. - name: Journals description: Journal entry CRUD. - name: Contacts description: Contact CRUD. - name: Banks description: Bank accounts. - name: Bank transactions description: Statement lines and AI-assisted upload. - name: Reports description: Financial statements (aligned with in-app reports). - name: Inventory description: Product and service catalog; stock tracking, sell, and restock. - name: Fixed Assets description: Capital asset acquisition and tracking. - name: Quotes description: >- Sales proposals that can be converted to invoices, income, or prepaid income. - name: Purchase Orders description: Vendor buying commitments that convert to inventory restocks. - name: Departments description: Reporting dimension for cost/profit allocation within a branch. - name: Projects description: Job costing and project tracking dimension attached to transactions. - name: Branches description: Multi-location dimension; reports and lists can filter by branch. paths: /purchase-orders: post: tags: - Purchase Orders summary: Create purchase order (manual or AI) description: >- Create a buying commitment to a vendor. Supports AI create when `prompt` is present. Use `/purchase-orders/{uuid}/convert-to-restock` when goods arrive. operationId: createPurchaseOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ManualPurchaseOrderCreate' responses: '200': description: Purchase order created content: application/json: schema: $ref: '#/components/schemas/AdamSuccessResponse' example: status: success message: Purchase order created successfully data: uuid: po-uuid-1 transaction_type: purchase_order status: draft document_number: PO-0042 narration: Q2 stock replenishment amount: 450000 currency: NGN '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ManualPurchaseOrderCreate: type: object required: - date - items example: date: '2026-04-05' delivery_date: '2026-04-20' currency: NGN document_number: PO-0042 narration: Q2 stock replenishment customer: v8e7d6c5b4a3418290f0e9d8c7b6a5947 items: - item_name: Wireless Mouse quantity: 50 selling_price: 9000 category: Inventory properties: date: type: string format: date description: Purchase order date. delivery_date: type: string format: date description: Expected delivery date. currency: type: string description: Currency code. document_number: type: string description: PO number; auto-assigned if omitted. narration: type: string description: PO title / description. memo: type: string description: Internal note. customer: type: string description: 'Vendor contact uuid, name, or email. Alias: `vendor`.' exchange_rate: type: number description: Default `1`. status: type: string description: Default `draft`. branch_uuid: type: string description: 'Branch id from `GET /branches`. Alias: `branch`.' department_uuid: type: string description: 'Department id from `GET /departments`. Alias: `department`.' project_uuid: type: string description: >- Project id from `GET /projects`. An unknown id is saved as sent and does not create a project. To add one from a name, send `project_name` and leave this off. items: type: array minItems: 1 items: $ref: '#/components/schemas/ManualDocumentLineItem' description: Line items. branch: type: string description: >- Branch id. Same as `branch_uuid`. Leave both off to use the business default branch. A name is not accepted, and a new branch is not created. An id that is not one of your branches is still saved, but it will not show under a location in reports. On an update, this name is ignored — send the id. department: type: string description: >- Department id. Same as `department_uuid`. An unknown id is saved as sent and does not create a department. To add one from a name, send `department_name` and leave this off. department_name: type: string description: >- Department name. Capitalization does not matter. If no department has that name, Tyms adds one and tags this document with it. Ignored when `department` or `department_uuid` is set. On an update, this name is ignored — send the id. project_name: type: string description: >- Project name, matched exactly, including capital letters. If no project has that name, Tyms adds an active project that starts today and ends in one month, then tags this document with it. Ignored when `project_uuid` is set. On an update, this name is ignored — send the id. employee: type: string description: >- Team member id. Same as `employee_uuid`. An unknown id is saved as sent and does not add a person. To add one from a name, send `employee_name` and leave this off. employee_uuid: type: string description: 'Team member id. Alias: `employee`.' employee_name: type: string description: >- Full name of the team member. If nobody matches, Tyms adds them. Ignored when `employee` or `employee_uuid` is set. On an update, this name is ignored — send the id. AdamSuccessResponse: type: object required: - status - message properties: status: type: string example: success message: type: string data: description: >- Single resource, array of resources, statement sections, or async job metadata — see each operation's example. meta: type: object additionalProperties: true description: >- Pagination (`page`, `limit`, `total`) and/or report range (`from`, `to`). Cash flow may include `previous_period_end`. ErrorResponse: type: object properties: status: type: string example: failed message: type: string ManualDocumentLineItem: type: object required: - item_name - quantity - selling_price - category properties: item_name: type: string description: 'Line label. Alias: `name`.' quantity: type: number description: Quantity sold or purchased. selling_price: type: number description: 'Unit price. On bills this is unit cost. Alias: `price`.' category: type: string description: >- Required. Revenue, expense, or inventory account — name, uuid, or account code. description: type: string description: Optional line description. tax: type: number description: >- Tax rate as a percentage (e.g. `7.5` = 7.5%). Preferred over `tax_uuid`. tax_uuid: type: string description: Optional tax record uuid instead of `tax` percentage. withholding_tax: type: number description: Withholding tax (WHT) rate as a percentage. withholding_tax_uuid: type: string description: Optional WHT uuid instead of `withholding_tax` percentage. discount: type: number description: Line discount value. discount_type: type: string enum: - percent - amount - fixed description: '`percent` or `amount` / `fixed`.' is_inventory: type: boolean description: '`true` if the line affects stock.' uuid: type: string description: Existing inventory item uuid when linking stock. securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: >- Business secret `tyms_sk_...` for business-scoped routes. Partner secret for register-business and referred-business distributor routes. x-default: your_tyms_sk_or_partner_key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.