---
updatedAt: 2026-08-27T21:57:09.000Z
agentTools:
  siteIndex: https://developer.jamf.com/llms.txt
  projectIndex: https://developer.jamf.com/platform-api/llms.txt
---

# Submit Distributor Purchase Order

Submits a distributor purchase order against the quote it references. The request is validated using the same rules as `POST /distributor/validate-purchase-order`; a purchase order that fails validation is rejected.

The response has no body. Jamf assigns the `jamfPoNumber` during processing, which is not synchronous with this request — poll `GET /distributor/purchase-orders/{jamfPoNumber}` or subscribe a webhook via `PATCH /distributor/configuration` to observe the outcome.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Jamf Account Partners API",
    "description": "Deal registrations, distributor quotes, and distributor purchase orders for Jamf channel partners",
    "version": "1.1.0",
    "termsOfService": "https://www.jamf.com/developer-resources/api-license-agreement/",
    "contact": {
      "name": "Jamf Developer",
      "url": "https://developer.jamf.com"
    }
  },
  "tags": [
    {
      "name": "distributor-purchase-orders",
      "description": "Operations for validating, submitting, and tracking distributor purchase orders raised against a quote."
    }
  ],
  "paths": {
    "/v1/distributor/purchase-orders": {
      "post": {
        "tags": [
          "distributor-purchase-orders"
        ],
        "operationId": "addDistributorPurchaseOrder",
        "summary": "Submit Distributor Purchase Order",
        "description": "Submits a distributor purchase order against the quote it references. The request is validated using the same rules as `POST /distributor/validate-purchase-order`; a purchase order that fails validation is rejected.\n\nThe response has no body. Jamf assigns the `jamfPoNumber` during processing, which is not synchronous with this request — poll `GET /distributor/purchase-orders/{jamfPoNumber}` or subscribe a webhook via `PATCH /distributor/configuration` to observe the outcome.",
        "requestBody": {
          "required": true,
          "description": "The purchase order to submit.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DistributorPurchaseOrder"
              },
              "example": {
                "quoteNumber": "Q-0012345",
                "poNumber": "PO-88231",
                "poDate": "2026-06-12",
                "currencyCode": "USD",
                "totalAmount": 48250,
                "lines": [
                  {
                    "sku": "JAMF-PRO-SUB",
                    "description": "Jamf Pro - Annual Subscription",
                    "quantity": 500,
                    "lineAmount": 48250
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The purchase order was created and accepted for processing. The response has no body, and no `Location` header is returned: the `jamfPoNumber` the purchase order will be addressed by is assigned during processing, after this response."
          },
          "400": {
            "$ref": "#/components/responses/PurchaseOrderBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/DistributorNotFound"
          },
          "500": {
            "$ref": "#/components/responses/UpstreamError"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": []
          }
        ]
      }
    }
  },
  "components": {
    "responses": {
      "PurchaseOrderBadRequest": {
        "description": "Bad Request. The purchase order failed validation against the quote it references (`UPSTREAM_ERROR`), or the request body could not be parsed as JSON (`MALFORMED_REQUEST_BODY`). The validation rules are the ones `POST /distributor/validate-purchase-order` reports, so call that endpoint to see which rule failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "httpStatus": 400,
              "traceId": "80f198ee56343ba864fe8b2a57d3eff7",
              "errors": [
                {
                  "code": "UPSTREAM_ERROR",
                  "field": null,
                  "description": "Failed to add purchase order via Skyway distributor service"
                }
              ]
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized. The access token is missing, invalid, or expired. The API Gateway rejects the request before it reaches the service.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "httpStatus": 401,
              "traceId": "80f198ee56343ba864fe8b2a57d3eff7",
              "errors": [
                {
                  "code": "UNAUTHORIZED",
                  "field": null,
                  "description": "The access token is missing, invalid, or expired."
                }
              ]
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden. The token is not an external M2M token, or it does not carry the scope required to reach this endpoint.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "httpStatus": 403,
              "traceId": "80f198ee56343ba864fe8b2a57d3eff7",
              "errors": [
                {
                  "code": "FORBIDDEN",
                  "field": null,
                  "description": "M2M token missing required scope"
                }
              ]
            }
          }
        }
      },
      "DistributorNotFound": {
        "description": "Not Found. The organization resolved from the access token is not registered as a Jamf distributor (`NOT_FOUND`), or the requested quote or purchase order does not exist for that distributor (`UPSTREAM_ERROR`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "httpStatus": 404,
              "traceId": "80f198ee56343ba864fe8b2a57d3eff7",
              "errors": [
                {
                  "code": "NOT_FOUND",
                  "field": null,
                  "description": "Unable to find organization for tenant service organization id 0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
                }
              ]
            }
          }
        }
      },
      "UpstreamError": {
        "description": "Internal Server Error. The upstream distributor platform failed to serve the request. Only upstream `400`, `404`, and `409` responses are relayed with their own status; every other upstream failure is reported as a `500`, since it describes Jamf's problem rather than the caller's. The `description` is deliberately generic; quote `traceId` when reporting the failure.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "example": {
              "httpStatus": 500,
              "traceId": "80f198ee56343ba864fe8b2a57d3eff7",
              "errors": [
                {
                  "code": "UPSTREAM_ERROR",
                  "field": null,
                  "description": "The request could not be completed"
                }
              ]
            }
          }
        }
      }
    },
    "schemas": {
      "DistributorPurchaseOrder": {
        "type": "object",
        "description": "A distributor purchase order raised against a quote.\n\nThe schema is shared by requests and responses. On submission, supply the quote being ordered against, the distributor's own purchase order details, and the lines; the Jamf-assigned fields (`jamfPoNumber`, `jamfOrderNumber`, `orderNumber`, `status`, `createdOn`, `lastModifiedOn`, `legalEntity`) are populated by Jamf during processing and are ignored if supplied.",
        "properties": {
          "jamfPoNumber": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Purchase order number Jamf assigned during processing. Use it to read the purchase order back. Assigned by Jamf; ignored on submission.",
            "example": "JPO-004512"
          },
          "createdOn": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "nullable": true,
            "description": "When Jamf received the purchase order. Assigned by Jamf; ignored on submission.",
            "example": "2026-06-12T16:04:55Z"
          },
          "lastModifiedOn": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "nullable": true,
            "description": "When the purchase order last changed. Assigned by Jamf; ignored on submission.",
            "example": "2026-06-13T08:31:12Z"
          },
          "jamfOrderNumber": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Sales order Jamf raised from this purchase order. Null until the purchase order has been processed. Assigned by Jamf; ignored on submission.",
            "example": "SO-119284"
          },
          "quoteNumber": {
            "type": "string",
            "description": "Quote this purchase order is raised against, as returned by `GET /distributor/quotes/{quoteNumber}`.",
            "example": "Q-0012345"
          },
          "poNumber": {
            "type": "string",
            "description": "The distributor's own purchase order number.",
            "example": "PO-88231"
          },
          "poDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Date the distributor raised the purchase order.",
            "example": "2026-06-12"
          },
          "orderNumber": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Order reference within the distributor platform. Assigned during processing; ignored on submission.",
            "example": "PO-88231-1"
          },
          "status": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Processing status of the purchase order. Assigned by Jamf; ignored on submission.",
            "example": "Processed"
          },
          "legalEntity": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Jamf legal entity contracting on the order. Taken from the quote; ignored on submission.",
            "example": "Jamf Software, LLC"
          },
          "paymentTerms": {
            "type": "string",
            "nullable": true,
            "description": "Payment terms that apply to the order.",
            "example": "Net 30"
          },
          "currencyCode": {
            "type": "string",
            "description": "ISO 4217 currency code that `totalAmount` and all line amounts are denominated in. Must match the quote.",
            "example": "USD"
          },
          "totalAmount": {
            "type": "number",
            "nullable": true,
            "description": "Total value of the purchase order in `currencyCode`. Validated against the quote total.",
            "example": 48250
          },
          "billingAddress": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DistributorAddress"
              }
            ],
            "description": "Address the order is billed to. Defaults to the quote's billing address when omitted.",
            "example": {
              "line1": "100 Washington Ave S",
              "city": "Minneapolis",
              "stateProvinceCode": "MN",
              "postalCode": "55401",
              "countryCode": "US"
            }
          },
          "shippingAddress": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DistributorAddress"
              }
            ],
            "description": "Address the order ships to. Defaults to the quote's shipping address when omitted.",
            "example": {
              "line1": "100 Washington Ave S",
              "city": "Minneapolis",
              "stateProvinceCode": "MN",
              "postalCode": "55401",
              "countryCode": "US"
            }
          },
          "lines": {
            "type": "array",
            "nullable": true,
            "description": "Line items on the purchase order.",
            "items": {
              "$ref": "#/components/schemas/DistributorPurchaseOrderLine"
            }
          }
        }
      },
      "DistributorPurchaseOrderLine": {
        "type": "object",
        "description": "A single line item on a distributor purchase order.",
        "properties": {
          "quantity": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "Number of units ordered.",
            "example": 500
          },
          "sku": {
            "type": "string",
            "description": "Stock-keeping unit being ordered. Must appear on the quote.",
            "example": "JAMF-PRO-SUB"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Description of the ordered product.",
            "example": "Jamf Pro - Annual Subscription"
          },
          "lineAmount": {
            "type": "number",
            "nullable": true,
            "description": "Value of this line in the purchase order's `currencyCode`.",
            "example": 48250
          }
        }
      },
      "DistributorAddress": {
        "type": "object",
        "description": "A billing or shipping address on a distributor quote or purchase order.",
        "properties": {
          "line1": {
            "type": "string",
            "nullable": true,
            "description": "First line of the street address.",
            "example": "100 Washington Ave S"
          },
          "line2": {
            "type": "string",
            "nullable": true,
            "description": "Second line of the street address, such as a suite or unit.",
            "example": "Suite 1100"
          },
          "line3": {
            "type": "string",
            "nullable": true,
            "description": "Third line of the street address, where one is used.",
            "example": "Attn: Accounts Payable"
          },
          "line4": {
            "type": "string",
            "nullable": true,
            "description": "Fourth line of the street address, where one is used.",
            "example": "Building C"
          },
          "city": {
            "type": "string",
            "nullable": true,
            "description": "City or locality.",
            "example": "Minneapolis"
          },
          "stateProvince": {
            "type": "string",
            "nullable": true,
            "description": "Full name of the state, province, or region.",
            "example": "Minnesota"
          },
          "stateProvinceCode": {
            "type": "string",
            "nullable": true,
            "description": "Abbreviated code for the state, province, or region.",
            "example": "MN"
          },
          "postalCode": {
            "type": "string",
            "nullable": true,
            "description": "Postal or ZIP code.",
            "example": "55401"
          },
          "countryCode": {
            "type": "string",
            "nullable": true,
            "description": "ISO 3166-1 alpha-2 country code.",
            "example": "US"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Full country name.",
            "example": "United States"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "description": "Standard Jamf error response body, returned for every non-2xx response raised by the service.",
        "required": [
          "httpStatus",
          "errors"
        ],
        "properties": {
          "httpStatus": {
            "type": "integer",
            "description": "HTTP status code of the response.",
            "example": 400
          },
          "traceId": {
            "type": "string",
            "nullable": true,
            "description": "Trace identifier correlating the response with Jamf server-side logs. Quote it when reporting a failure. Null when the request carried no active trace.",
            "example": "80f198ee56343ba864fe8b2a57d3eff7"
          },
          "errors": {
            "type": "array",
            "description": "Every problem found with the request. Always holds at least one entry.",
            "items": {
              "$ref": "#/components/schemas/ApiErrorItem"
            }
          }
        }
      },
      "ApiErrorItem": {
        "type": "object",
        "description": "A single problem with the request.",
        "required": [
          "code",
          "description"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable, stable classification of the problem. Values used by this API include `MALFORMED_REQUEST_BODY`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `UPSTREAM_ERROR`, and `INTERNAL_ERROR`. Prefer this over matching on `description`.",
            "example": "UPSTREAM_ERROR"
          },
          "field": {
            "type": "string",
            "nullable": true,
            "description": "Request field the problem relates to, in dotted notation for a nested field. Null when the problem is not about one field.",
            "example": null
          },
          "description": {
            "type": "string",
            "description": "Human-readable explanation, for troubleshooting rather than display to an end user. Generic for server-side failures, which are correlated through `traceId` instead.",
            "example": "Failed to add purchase order via Skyway distributor service"
          }
        }
      }
    },
    "securitySchemes": {
      "OAuth2ClientCredentials": {
        "type": "oauth2",
        "description": "Obtain an access token by calling the API Gateway's token endpoint using the OAuth2 client-credentials flow.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{region}.api.jamfcloud.com/auth/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://{region}.api.jamfcloud.com/partners",
      "description": "Jamf Production API Gateway",
      "variables": {
        "region": {
          "default": "us",
          "enum": [
            "us"
          ],
          "description": "Select the regional gateway"
        }
      }
    }
  ],
  "security": [
    {
      "OAuth2ClientCredentials": []
    }
  ]
}
```