---
title: "Update purchase order status"
method: PATCH
path: "/purchaseorders/{id}/status"
tags: ["Purchase Orders"]
---

# Update purchase order status

`PATCH /purchaseorders/{id}/status`

## Path parameters

- `id` number, required

## Query parameters

- `skipWebhook` boolean

## Request body

- object
  - `status` 'APPROVED' | 'CANCELED' | 'COMPLETED' | 'DECLINED' | 'PARTIALLY_FULFILLED' | 'PENDING', required — Here is a list of valid status transitions: | Current Status | Allowed Transitions | Description | |---------------------|------------------------------------------|-------------------------------------------------------| | `REQUESTED` | `CANCELED` `DECLINED` `PENDING` | Initial state when PO is first created | | `PENDING` | `APPROVED` `CANCELED` `DECLINED` | PO is awaiting approval | | `DECLINED` | `CANCELED` `PENDING` | PO was rejected and needs revision | | `APPROVED` | `CANCELED` or start receiving items | PO is approved and items can be received | | `PARTIALLY_FULFILLED`| `COMPLETED` | Some items have been received | | `CANCELED` | None | PO has been canceled and cannot be modified | | `COMPLETED` | `PARTIALLY_FULFILLED` | All items have been received | *Notes*: - Status changes trigger notifications to relevant users and vendors - You can subscribe to status changes using [webhooks](#tag/Subscriptions-and-Webhooks) - The `DECLINED` status is displayed as 'Rejected' in the application interface - Moving to `PARTIALLY_FULFILLED` happens automatically when items are received - Use the optional `reviewNote` field to provide feedback when declining a purchase order
  - `reviewNote` string, nullable — Notes to be left for changes to be made when sending a Purchase Order for revision

## Response `200`

Successfully updated Purchase Order

- object
  - `purchaseOrder` object, required
    - `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 update the Purchase Order
- `401` — Invalid token
- `403` — Failed to update the Purchase Order
- `404` — Could not find the specified Purchase Order.

---

[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)