---
title: Create a purchase order from an external provider payload
slug: create-a-purchase-order-from-an-external-provider-payload
docTags:
createdAt: 2026-09-15T14:46:26.795Z
---
{
"id": "iRzx25L84oYoTocI9SRUA",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://developer.digitail.io/api/v1/external-purchase-orders",
"servers": [
{
"url": "https://developer.digitail.io/api/v1/external-purchase-orders",
"description": "Sandbox server (uses test data)"
},
{
"url": "https://vet.digitail.io/api/v1/external-purchase-orders",
"description": "Production server (uses live data)"
}
],
"name": "Create a purchase order from an external provider payload",
"description": "Permissions needed: CREATE_ORDERS.
\nImports a purchase order from an external provider payload (the same payload shape consumed by the Vetcove webhook), under standard API authentication.
\nThe authenticated vet becomes the purchase order's vet. The target clinic is resolved from the auth context via the X-ClinicId header; when omitted it falls back to the authenticated vet's active clinic. The clinic is never read from the request body.
\nFor each item the importer finds or creates the product (and its manufacturer/producer), computes cogs from unit_price and units, and creates the purchase order line. The supplier is matched or created from supplier.name. The created purchase order is returned synchronously with status PENDING, document type INVOICE, and series EXTERNAL.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [
{
"name": "accept",
"type": "string",
"kind": "optional",
"description": "Generated from available response content types",
"enum": [
"application/json"
],
"default": "application/json"
},
{
"kind": "optional",
"name": "X-ClinicId",
"type": "integer",
"example": 605,
"description": "Id of the clinic to create the purchase order for. Must be a clinic the authenticated vet is employed by. Defaults to the vet's active clinic.\n"
}
],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "required",
"name": "body",
"type": "object",
"example": "{\"timestamp\":\"2025-06-11T10:00:00.000Z\",\"id\":\"HF-TEST-001\",\"supplier\":{\"id\":null,\"name\":\"Covetrus\"},\"user\":{\"id\":1,\"first_name\":\"Kat\",\"last_name\":\"Stevens\"},\"items\":[{\"id\":148,\"is_linked\":true,\"provider_item_id\":64002,\"sku\":\"026143\",\"name\":\"GlycoFlex 3 Bite-Sized Chews: 120 Count\",\"quantity\":4,\"unit_price\":2000,\"total_price\":8000,\"units\":120,\"unit_measurement\":\"chew\",\"pack_type\":\"Bag\",\"manufacturer_name\":\"Vetri-Science\"},{\"id\":\"\",\"is_linked\":false,\"provider_item_id\":191172,\"sku\":\"606029\",\"name\":\"PVC Cuffed Endotracheal Tube: 5.5mm\",\"quantity\":2,\"unit_price\":160,\"total_price\":320,\"units\":1,\"unit_measurement\":\"tube\",\"pack_type\":\"\",\"manufacturer_name\":\"VetOne\"}]}",
"description": "",
"schema": [
{
"name": "timestamp",
"kind": "required",
"type": "string",
"description": "Purchase order timestamp. Used for both the purchase order date and the document date.\n",
"example": "2025-06-11T10:00:00.000Z",
"format": "date-time"
},
{
"name": "id",
"kind": "required",
"type": "object",
"description": "Provider purchase order id, stored as the document number.
",
"complexType": "oneOf",
"complexItems": [],
"schema": []
},
{
"name": "provider",
"kind": "optional",
"type": "string",
"description": "Provider of the order. external is the only supported value and the default. Whatever string you send here is kept in the purchase order's metadata.
",
"example": "external",
"default": "external",
"maxLength": 191
},
{
"name": "supplier",
"kind": "required",
"type": "object",
"description": "Supplier matched or created from supplier.name before the purchase order is created. supplier.id is ignored.
",
"example": "",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "integer",
"nullable": true,
"description": "",
"example": ""
},
{
"name": "name",
"kind": "required",
"type": "string",
"description": "",
"example": "Covetrus"
}
]
},
{
"name": "user",
"kind": "optional",
"type": "object",
"nullable": true,
"description": "Optional provider user info. Stored on the purchase order metadata; does NOT determine the purchase order's vet (the authenticated vet is always used).
",
"example": "",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "integer",
"nullable": true,
"description": "",
"example": 1
},
{
"name": "first_name",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "",
"example": "Kat"
},
{
"name": "last_name",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "",
"example": "Stevens"
}
]
},
{
"name": "items",
"kind": "required",
"type": "array",
"description": "Purchase order line items. Each item is used to find or create a product, compute cogs, and create a purchase order item.
",
"example": "",
"itemType": "object",
"customType": "object[]",
"schema": [
{
"name": "id",
"kind": "required",
"type": "object",
"description": "Digitail product id, or an empty string when the provider item is not linked to an existing product.
",
"complexType": "oneOf",
"complexItems": [],
"schema": []
},
{
"name": "is_linked",
"kind": "required",
"type": "boolean",
"description": "Whether the provider item is already linked to a Digitail product. When false a new product is always created.\n",
"example": true
},
{
"name": "provider_item_id",
"kind": "required",
"type": "object",
"description": "External provider item id. Stored on the product as its external id and used to match previously imported products.\n",
"complexType": "oneOf",
"complexItems": [],
"schema": []
},
{
"name": "sku",
"kind": "required",
"type": "string",
"description": "Product barcode / SKU used when finding or creating a product.
",
"example": "026143"
},
{
"name": "name",
"kind": "required",
"type": "string",
"description": "Product name used when finding or creating a product.",
"example": "GlycoFlex 3 Bite-Sized Chews: 120 Count"
},
{
"name": "quantity",
"kind": "required",
"type": "integer",
"description": "Number of packs ordered.",
"example": 4,
"minimum": 1
},
{
"name": "unit_price",
"kind": "required",
"type": "integer",
"description": "Pack price in minor currency units (cents). The importer divides this by 100 and then by units to compute cogs per stock unit.
",
"example": 2000,
"minimum": 0
},
{
"name": "total_price",
"kind": "optional",
"type": "integer",
"nullable": true,
"description": "Line total in minor currency units. Currently ignored.",
"example": 8000
},
{
"name": "units",
"kind": "required",
"type": "integer",
"description": "Number of stock units inside one ordered pack. The line quantity is quantity * units.
",
"example": 120,
"minimum": 1
},
{
"name": "unit_measurement",
"kind": "required",
"type": "string",
"nullable": true,
"description": "Unit label used when creating a new product. null falls back to Unit.
",
"example": "chew"
},
{
"name": "pack_type",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "Provider pack type. Currently ignored.",
"example": "Bag"
},
{
"name": "manufacturer_name",
"kind": "required",
"type": "string",
"description": "Manufacturer name used to find or create the producer.",
"example": "Vetri-Science"
},
{
"name": "client_name",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "Optional client-facing product name used when creating a new product.
",
"example": "GlycoFlex 3"
},
{
"name": "staff_description",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "Optional staff description used when creating a new product.",
"example": "Joint support chew"
},
{
"name": "batch_no",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "Batch (lot) number of the delivered stock, saved on the purchase order line.
",
"example": "BATCH-001"
},
{
"name": "expiration_date",
"kind": "optional",
"type": "string",
"nullable": true,
"description": "Expiry date of the delivered batch, saved on the purchase order line. Must be after timestamp.
",
"example": "2027-01-01T00:00:00Z",
"format": "date-time"
}
]
}
],
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "passport",
"name": "passport",
"kind": "optional",
"type": "oauth2",
"description": "Laravel passport oauth2 security.",
"oauth2Flows": {
"authorizationCode": {
"authorizationUrl": "https://digitail.test/oauth/authorize",
"tokenUrl": "https://digitail.test/oauth/token",
"refreshUrl": "https://digitail.test/oauth/token"
}
}
},
{
"id": "Bearer",
"name": "Bearer",
"kind": "optional",
"type": "http",
"scheme": "bearer"
}
],
"cookieParameters": []
},
"responses": [
{
"statusCode": "201",
"description": "Purchase order created successfully.",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"schema": [
{
"name": "data",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/paths/~1api~1v1~1purchase-orders~1%7Bid%7D/get/responses/200/content/application~1json/schema/properties/data",
"customType": "data",
"schema": []
}
],
"isExpanded": true
}
]
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "2WPjea2RBDXXqLrveMHr4",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://developer.digitail.io/api/v1/external-purchase-orders \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"timestamp\": \"2025-06-11T10:00:00.000Z\",\n \"id\": \"\",\n \"provider\": \"external\",\n \"supplier\": {\n \"name\": \"Covetrus\"\n },\n \"items\": [\n {\n \"id\": \"\",\n \"is_linked\": true,\n \"provider_item_id\": \"\",\n \"sku\": \"026143\",\n \"name\": \"GlycoFlex 3 Bite-Sized Chews: 120 Count\",\n \"quantity\": 4,\n \"unit_price\": 2000,\n \"units\": 120,\n \"unit_measurement\": \"chew\",\n \"manufacturer_name\": \"Vetri-Science\"\n }\n ]\n }'"
},
{
"id": "aj7Ssa6__uTXznlI9G4ut",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"timestamp\": \"2025-06-11T10:00:00.000Z\",\n \"id\": \"\",\n \"provider\": \"external\",\n \"supplier\": {\n \"name\": \"Covetrus\"\n },\n \"items\": [\n {\n \"id\": \"\",\n \"is_linked\": true,\n \"provider_item_id\": \"\",\n \"sku\": \"026143\",\n \"name\": \"GlycoFlex 3 Bite-Sized Chews: 120 Count\",\n \"quantity\": 4,\n \"unit_price\": 2000,\n \"units\": 120,\n \"unit_measurement\": \"chew\",\n \"manufacturer_name\": \"Vetri-Science\"\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://developer.digitail.io/api/v1/external-purchase-orders\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "qib50zsl4xnQS8QSIASrJ",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://developer.digitail.io/api/v1/external-purchase-orders\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"timestamp\": \"2025-06-11T10:00:00.000Z\",\n \"id\": \"\",\n \"provider\": \"external\",\n \"supplier\": {\n \"name\": \"Covetrus\"\n },\n \"items\": [\n {\n \"id\": \"\",\n \"is_linked\": true,\n \"provider_item_id\": \"\",\n \"sku\": \"026143\",\n \"name\": \"GlycoFlex 3 Bite-Sized Chews: 120 Count\",\n \"quantity\": 4,\n \"unit_price\": 2000,\n \"units\": 120,\n \"unit_measurement\": \"chew\",\n \"manufacturer_name\": \"Vetri-Science\"\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "2WiA7dxBtdFyWPvIaabGK",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://developer.digitail.io/api/v1/external-purchase-orders\"\n\npayload = json.dumps({\n \"timestamp\": \"2025-06-11T10:00:00.000Z\",\n \"id\": \"\",\n \"provider\": \"external\",\n \"supplier\": {\n \"name\": \"Covetrus\"\n },\n \"items\": [\n {\n \"id\": \"\",\n \"is_linked\": True,\n \"provider_item_id\": \"\",\n \"sku\": \"026143\",\n \"name\": \"GlycoFlex 3 Bite-Sized Chews: 120 Count\",\n \"quantity\": 4,\n \"unit_price\": 2000,\n \"units\": 120,\n \"unit_measurement\": \"chew\",\n \"manufacturer_name\": \"Vetri-Science\"\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "2WPjea2RBDXXqLrveMHr4"
},
"results": {
"languages": [
{
"id": "eeGnXUkdiVX5soNxILCh1",
"language": "201",
"code": "// Purchase order created successfully.\n{\n \"data\": {}\n}"
}
],
"selectedLanguageId": "eeGnXUkdiVX5soNxILCh1"
}
},
"children": [
{
"text": ""
}
]
}