Create a purchase order from an external provider payload

1 min

POST

https://developer.digitail.io/api/v1/external-purchase-orders

Permissions needed: CREATE_ORDERS.

Imports a purchase order from an external provider payload (the same payload shape consumed by the Vetcove webhook), under standard API authentication.

The 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.

For 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.

Header Parameters

X-ClinicIdinteger
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.

Body Parameters

bodyobjectrequired
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"
    }
  ]
}
```
- timestampstring<date-time>required
  Example
  2025-06-11T10:00:00.000Z
  Description
  Purchase order timestamp. Used for both the purchase order date and the document date.
  Format
  date-time
- idobjectrequired
  Description
  Provider purchase order id, stored as the document number.
- providerstring
  Example
  external
  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.
  Default
  external
  Max Length
  191
- supplierobjectrequired
  Description
  Supplier matched or created from supplier.name before the purchase order is created. supplier.id is ignored.
  - idinteger
  - namestringrequired
    Example
    Covetrus
- userobject
  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).
  - idinteger
    Example
    1
  - first_namestring
    Example
    Kat
  - last_namestring
    Example
    Stevens
- itemsobject[]required
  Description
  Purchase order line items. Each item is used to find or create a product, compute cogs, and create a purchase order item.
  - idobjectrequired
    Description
    Digitail product id, or an empty string when the provider item is not linked to an existing product.
  - is_linkedbooleanrequired
    Example
    true
    Description
    Whether the provider item is already linked to a Digitail product. When false a new product is always created.
  - provider_item_idobjectrequired
    Description
    External provider item id. Stored on the product as its external id and used to match previously imported products.
  - skustringrequired
    Example
    026143
    Description
    Product barcode / SKU used when finding or creating a product.
  - namestringrequired
    Example
    GlycoFlex 3 Bite-Sized Chews: 120 Count
    Description
    Product name used when finding or creating a product.
  - quantityintegerrequired
    Example
    4
    Description
    Number of packs ordered.
    Minimum
    1
  - unit_priceintegerrequired
    Example
    2000
    Description
    Pack price in minor currency units (cents). The importer divides this by 100 and then by units to compute cogs per stock unit.
    Minimum
    0
  - total_priceinteger
    Example
    8000
    Description
    Line total in minor currency units. Currently ignored.
  - unitsintegerrequired
    Example
    120
    Description
    Number of stock units inside one ordered pack. The line quantity is quantity * units.
    Minimum
    1
  - unit_measurementstringrequired
    Example
    chew
    Description
    Unit label used when creating a new product. null falls back to Unit.
  - pack_typestring
    Example
    Bag
    Description
    Provider pack type. Currently ignored.
  - manufacturer_namestringrequired
    Example
    Vetri-Science
    Description
    Manufacturer name used to find or create the producer.
  - client_namestring
    Example
    GlycoFlex 3
    Description
    Optional client-facing product name used when creating a new product.
  - staff_descriptionstring
    Example
    Joint support chew
    Description
    Optional staff description used when creating a new product.
  - batch_nostring
    Example
    BATCH-001
    Description
    Batch (lot) number of the delivered stock, saved on the purchase order line.
  - expiration_datestring<date-time>
    Example
    2027-01-01T00:00:00Z
    Description
    Expiry date of the delivered batch, saved on the purchase order line. Must be after timestamp.
    Format
    date-time

Responses

201Purchase order created successfully.

object
- datadata

curl

curl --request POST \
     --url https://developer.digitail.io/api/v1/external-purchase-orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "timestamp": "2025-06-11T10:00:00.000Z",
     "id": "",
     "provider": "external",
     "supplier": {
     "name": "Covetrus"
     },
     "items": [
     {
     "id": "",
     "is_linked": true,
     "provider_item_id": "",
     "sku": "026143",
     "name": "GlycoFlex 3 Bite-Sized Chews: 120 Count",
     "quantity": 4,
     "unit_price": 2000,
     "units": 120,
     "unit_measurement": "chew",
     "manufacturer_name": "Vetri-Science"
     }
     ]
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "timestamp": "2025-06-11T10:00:00.000Z",
   "id": "",
   "provider": "external",
   "supplier": {
      "name": "Covetrus"
   },
   "items": [
      {
         "id": "",
         "is_linked": true,
         "provider_item_id": "",
         "sku": "026143",
         "name": "GlycoFlex 3 Bite-Sized Chews: 120 Count",
         "quantity": 4,
         "unit_price": 2000,
         "units": 120,
         "unit_measurement": "chew",
         "manufacturer_name": "Vetri-Science"
      }
   ]
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://developer.digitail.io/api/v1/external-purchase-orders", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://developer.digitail.io/api/v1/external-purchase-orders")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "timestamp": "2025-06-11T10:00:00.000Z",
   "id": "",
   "provider": "external",
   "supplier": {
      "name": "Covetrus"
   },
   "items": [
      {
         "id": "",
         "is_linked": true,
         "provider_item_id": "",
         "sku": "026143",
         "name": "GlycoFlex 3 Bite-Sized Chews: 120 Count",
         "quantity": 4,
         "unit_price": 2000,
         "units": 120,
         "unit_measurement": "chew",
         "manufacturer_name": "Vetri-Science"
      }
   ]
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://developer.digitail.io/api/v1/external-purchase-orders"

payload = json.dumps({
   "timestamp": "2025-06-11T10:00:00.000Z",
   "id": "",
   "provider": "external",
   "supplier": {
      "name": "Covetrus"
   },
   "items": [
      {
         "id": "",
         "is_linked": True,
         "provider_item_id": "",
         "sku": "026143",
         "name": "GlycoFlex 3 Bite-Sized Chews: 120 Count",
         "quantity": 4,
         "unit_price": 2000,
         "units": 120,
         "unit_measurement": "chew",
         "manufacturer_name": "Vetri-Science"
      }
   ]
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

201

// Purchase order created successfully.
{
  "data": {}
}