--- title: "Create Purchase Orders" method: POST path: "/purchase_orders" tags: ["Purchase Orders"] --- # Create Purchase Orders `POST /purchase_orders` ## Request - Base URL: `https://secure.fleetio.com/api` - URL: `https://secure.fleetio.com/api/purchase_orders` - Auth: API key in header `Authorization` and API key in header `Account-Token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a new Purchase Order ## Request body - object - `description` string, nullable - `label_list` string: A comma separated list of tags associated with this record. The only delimiter allowed is a comma (`,`). Please remove any commas from your labels before saving the record. - `vendor_id` integer - `part_location_id` integer: The Fleetio ID of the [Part Location](/docs/api/v-1-part-locations-index) for the [Part](/docs/api/parts) being purchased. - `number` integer, required: Must be unique within the scope of your Account. You can either generate your own number or leave it blank and Fleetio will generate one for you. Fleetio will use the next number in the sequence based on your existing Purchase Orders. This becomes the unique identifier, even in endpoints. Id is never used. - `discount_type` 'fixed' | 'percentage', nullable: The type of discount applied to this record. - `discount_percentage` number, float: The discount percentage. This field should be present when `discount_type` is set to `percentage`. - `discount` number: The actual value of the discount - `shipping` number: The cost of shipping - `tax_1_percentage` number: The primary tax percentage amount. This field should be present when `tax_1_type` is set to `percentage`. - `tax_1` number, float: The primary tax amount. - `tax_1_type` 'fixed' | 'percentage', nullable: The type of tax to apply to this record. - `tax_2_percentage` number: The secondary tax percentage amount. This field should be present when `tax_2_type` is set to `percentage`. Note that this secondary tax must be configured in your [Account Settings](https://help.fleetio.com/s/article/Account-Settings#tax). - `tax_2` number, float: The secondary tax amount. Note that this secondary tax must be configured in your [Account Settings](https://help.fleetio.com/s/article/Account-Settings#tax). - `tax_2_type` 'fixed' | 'percentage', nullable: The type of tax to apply to this record. - `custom_fields` CustomFields, nullable: *Full details on working with Custom Fields [here](/docs/overview/custom-fields). - `purchase_order_line_items_attributes` object[] - `part_id` integer: The Fleetio ID of the [Part](/docs/api/parts) being purchased. - `quantity` integer: How many of this `Part` to be purchased. - `unit_cost` number, float: The cost of this `Part` (per unit). ## Response `201` OK - PurchaseOrderCreated, nullable: A Purchase Order - `id` integer, required - `created_at` string, date-time: The date and time at which this record was created. - `updated_at` string, date-time: The date and time at which this record was most recently updated. - `discount_type` 'fixed' | 'percentage', nullable, required: The type of discount applied to this record. - `discount_percentage` number, float, nullable, required: The discount percentage. This field should be present when `discount_type` is set to `percentage`. - `discount_cents` integer, nullable: The discount amount in cents. - `tax_1_type` 'fixed' | 'percentage', nullable, required: The type of tax to apply to this record. - `tax_1_percentage` number, float, nullable, required: The primary tax percentage amount. This field should be present when `tax_1_type` is set to `percentage`. - `tax_1_cents` integer, nullable: The primary tax amount in cents. - `tax_2_type` 'fixed' | 'percentage', nullable, required: The type of tax to apply to this record. - `tax_2_percentage` number, float, nullable, required: The secondary tax percentage amount. This field should be present when `tax_2_type` is set to `percentage`. Note that this secondary tax must be configured in your [Account Settings](https://help.fleetio.com/s/article/Account-Settings#tax). - `tax_2_cents` integer, nullable: The secondary tax amount in cents. - `shipping_cents` integer, nullable: The shipping amount in cents. - `account_id` integer, required - `number` integer, required: Must be unique within the scope of your Account. You can either generate your own number or leave it blank and Fleetio will generate one for you. Fleetio will use the next number in the sequence based on your existing Purchase Orders. This becomes the unique identifier, even in endpoints. Id is never used. - `description` string, nullable, required: Open text field for Purchase Order description. - `label_list` string[], required: A list of tags associated with this record. - `submitted_for_approval_at` string, date-time, nullable, required: The date and time at which this Purchase Order was submitted for approval. - `rejected_at` string, date-time, nullable, required: The date and time at which this Purchase Order was rejected. - `approved_at` string, date-time, nullable, required: The date and time at which this Purchase Order was approved. - `purchased_at` string, date-time, nullable, required: The date and time at which this Purchase Order was purchased. - `received_partial_at` string, date-time, nullable, required: The date and time at which this Purchase Order was partially received. - `received_full_at` string, date-time, nullable, required: The date and time at which this Purchase Order was fully received. - `closed_at` string, date-time, nullable, required: The date and time at which this Purchase Order was closed. - `state` 'draft' | 'submitted_for_approval' | 'rejected' | 'approved' | 'purchased' | 'received_partial' | 'received_full' | 'closed', nullable, required: See the [Purchase Order Lifecycle Guide](/docs/guides/inventory/purchase-order-lifecycle) for more information about Purchase Order states and how to transition between them. - `custom_fields` CustomFields, nullable, required: *Full details on working with Custom Fields [here](/docs/overview/custom-fields). - `part_location_id` integer, nullable, required: The ID of the `Part Location` associated with this Purchase Order. Optional in the `draft` state. - `vendor_id` integer, nullable, required: The ID of the [Vendor](/docs/api/vendors) associated with this Purchase Order. - `purchase_order_status_id` integer, nullable - `created_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who created this Purchase Order. - `rejected_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who closed this Purchase Order. - `submitted_for_approval_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who submitted this Purchase Order for approval. - `approved_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who approved this Purchase Order. - `purchased_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who purchased this Purchase Order. - `received_partial_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who partially received this Purchase Order. - `received_full_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who fully received this Purchase Order. - `closed_by_id` integer, nullable: The ID of the [Vendor](/docs/api/vendors) associated with the User who closed this Purchase Order. - `documents_count` integer, nullable, required: The number of documents attached to this Purchase Order. - `comments_count` integer, nullable, required: The number of `Comments` on this Purchase Order. - `subtotal_cents` integer, nullable: The subtotal amount in cents. - `total_amount_cents` integer, nullable: The total amount in cents. - `watchers_count` integer: The count of watchers associated with the record. - `watchable_options` object: Options related to watching the record. - `bulk_watch_record` boolean: Indicates if a bulk watch record is created. - `skip_automatic_watchers_callbacks` boolean: Indicates if automatic watchers callbacks are skipped. ## Other responses - `401`: Request could not be authenticated - `403`: Insufficient permission to perform this operation - `422`: Unprocessable Entity - `500`: Something unexpected happened --- [API](https://skmtc.dev/fleetio/apis/fleetio-developer-api.md) - [All operations](https://skmtc.dev/fleetio/apis/fleetio-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fleetio/apis/fleetio-developer-api/revisions/49558d744bd7?raw)