---
title: "Create new purchase order"
method: POST
path: "/purchaseorders"
tags: ["Purchase Orders"]
---

# Create new purchase order

`POST /purchaseorders`

## Query parameters

- `skipWebhook` boolean

## Headers

- `x-organization-id` integer

## Request body

- object
  - `note` string, nullable — Notes left for Purchase Orders
  - `dueDate` string, nullable — Due date of Purchase Order
  - `vendorId` number, nullable, required — ID of vendor that this Purchase Order is associated with
  - `overrideNumber` string, nullable — Custom number/identifier for Purchase Order
  - `deletedAt` string, date-time, nullable — Date at which the Purchase Order was deleted
  - `vendorContactIds` number[] — List of vendor contact IDs in the Purchase Order
  - `shippingAddress` object, nullable — Shipping address in the Purchase Order
    - `city` string, required
    - `country` string, required
    - `postalCode` string, required
    - `state` string, required
    - `street` string, required
    - `label` string, nullable — A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
  - `shippingAddressId` number, nullable — Shipping address Id in the Purchase Order
  - `billingAddress` object, nullable — Billing address in the Purchase Order
    - `city` string, required
    - `country` string, required
    - `postalCode` string, required
    - `state` string, required
    - `street` string, required
    - `label` string, nullable — A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
  - `billingAddressId` number, nullable — Billing address Id in the Purchase Order
  - `extraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Ordered Date")
  - `items` object[], required — List of items in the Purchase Order
    - `partId` number, nullable — ID of the part this item is related to
    - `name` string, nullable
    - `partNumber` string, nullable
    - `price` number, nullable — Total price of items in cents
    - `quantityOrdered` number, required — Represent the amount of units for this item that were ordered in the purchase order.
    - `quantityReceived` number, nullable — Represents the total amount of this specific item that has been received to date.
    - `unitCost` number, nullable — Price of a single item in cents
    - `extraFields` object — Custom Fields on the entity. Deprecated: Use `lineExtraFields` instead.
    - `lineExtraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Ordered Date")
  - `costs` object[] — List of costs in the Purchase Order
    - `name` string, required — Description of the cost
    - `type` 'AMOUNT_NON_TAXABLE' | 'AMOUNT_TAXABLE' | 'PERCENT_TAXABLE', required — Type of cost in either cents or percent. Accepted types in cents are AMOUNT_TAXABLE and AMOUNT_NON_TAXABLE. For percentage use PERCENT_TAXABLE
    - `amount` number, required
  - `title` string, nullable — Title of the Purchase Order. Will be ignored if organization setting for custom purchase order titles is disabled.

## Response `201`

Successfully created Purchase Order

- object
  - `id` number, required — Global ID of the Purchase Order
  - `note` string, nullable — Notes left for Purchase Orders
  - `title` string, nullable — Title of the Purchase Order.
  - `reviewNote` string, nullable — Notes to be left for changes to be made when sending a Purchase Order for revision
  - `status` string, nullable, required — Status of the Purchase Order. Supported values are APPROVED, CANCELED, COMPLETED, DECLINED, PARTIALLY_FULFILLED, PENDING, REQUESTED
  - `dueDate` string, nullable — Due date of Purchase Order
  - `creatorId` number — ID of the user that created this Purchase Order
  - `vendorId` number, nullable — ID of vendor that this Purchase Order is associated with
  - `autoGeneratedNumber` number, nullable — Autogenerated Purchase Order number
  - `overrideNumber` string, nullable — Custom number/identifier for Purchase Order
  - `approverId` number, nullable — ID of the user who approved the Purchase Order
  - `approvalDate` string, nullable — Date the Purchase Order was approved
  - `createdAt` string, date-time, nullable — Date the Purchase Order was created
  - `updatedAt` string, nullable — Date the Purchase Order was last updated
  - `deletedAt` string, date-time, nullable — Date at which the Purchase Order was deleted
  - `items` object[], required — List of items in the Purchase Order
    - `id` number, required — ID of the item
    - `partId` number, nullable — ID of the part this item is related to
    - `name` string, nullable
    - `partNumber` string, nullable
    - `price` number, nullable — Total price of items in cents
    - `priceDecimal` string, nullable — Total price of items as a decimal value
    - `quantityOrdered` number, required — Represent the amount of units for this item that were ordered in the purchase order.
    - `quantityReceived` number, nullable — Represents the total amount of this specific item that has been received to date.
    - `unitCost` number, nullable — Price of a single item in cents
    - `unitCostDecimal` string, nullable — Price of a single item as a decimal value
    - `fulfillments` object[] — Fulfillment information for the item's fulfillment locations.
      - `id` number — ID of the item fulfillment
      - `locationId` number, nullable — ID of the location where the item was fulfilled
      - `quantityReceived` string — Quantity of the item fulfilled to this location
      - `isLegacy` boolean — Indicates the location is a legacy location. This is used to determine if this fulfillment was done before enablement of the multi-location parts feature.
    - `extraFields` object — Custom Fields on the entity. Deprecated: Use `lineExtraFields` instead.
    - `lineExtraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Ordered Date")
    - `partExtraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Part Number")
  - `costs` object[] — List of costs in the Purchase Order
    - `id` number — ID of the cost
    - `name` string, required — Description of the cost
    - `type` 'AMOUNT_NON_TAXABLE' | 'AMOUNT_TAXABLE' | 'PERCENT_TAXABLE', required — Type of cost in either cents or percent. Accepted types in cents are AMOUNT_TAXABLE and AMOUNT_NON_TAXABLE. For percentage use PERCENT_TAXABLE
    - `amount` number, required
  - `thumbnail` object, nullable
    - `id` number, required — Global ID of the attachment
    - `mimeType` string, required — MIME type of the file
    - `fileName` string, required — Attachment's file name
    - `url` string, required — Url of the file. Valid for 60 minutes.
    - `createdAt` string, date-time, required — Date & time at which the attachment was uploaded
    - `width` number, nullable — Width if the file is an image
    - `height` number, nullable — Height if the file is an image
  - `attachments` object[] — List of attachments linked to the Purchase Order
    - `id` number, required — Global ID of the attachment
    - `mimeType` string, required — MIME type of the file
    - `fileName` string, required — Attachment's file name
    - `url` string, required — Url of the file. Valid for 60 minutes.
    - `createdAt` string, date-time, required — Date & time at which the attachment was uploaded
    - `width` number, nullable — Width if the file is an image
    - `height` number, nullable — Height if the file is an image
  - `vendorContactIds` number[] — List of vendor contact IDs in the Purchase Order
  - `shippingAddress` object, nullable — Shipping address in the Purchase Order
    - `city` string, required
    - `country` string, required
    - `postalCode` string, required
    - `state` string, required
    - `street` string, required
    - `label` string, nullable — A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
  - `billingAddress` object, nullable — Billing address in the Purchase Order
    - `city` string, required
    - `country` string, required
    - `postalCode` string, required
    - `state` string, required
    - `street` string, required
    - `label` string, nullable — A string to specify how the address will be displayed - Defaults to Street, City, Province/State, Postal Code, Country
  - `extraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Ordered Date")

## Other responses

- `400` — Failed to create the Purchase Order
- `401` — Invalid token
- `403` — Failed to create the Purchase Order
- `404` — Could not find the specified Purchase Order.
- `429` — Too many requests. Please retry in 10 seconds

---

[API](https://skmtc.net/getmaintainx/apis/maintainx-api.md) · [All operations](https://skmtc.net/getmaintainx/apis/maintainx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getmaintainx/maintainx-api/revisions/ef9153fcac7c/schema)