Enterprise Feature
This feature is only available to customers with an enterprise Platform subscription. Please get in touch to discuss enabling it on your account.
The Purchase Orders API allows solution developers to store information in the Platform describing the purchase orders in their supply chain. This is normally done at the time when products are ordered from a supplier, supplying a record of exact quantities ordered.
Each purchase order created contains details on the parties involved in the creation of that order (such as the manufacturer or supplier, and the buyer), as well as the product type or SKU being produced and at which quantities.
API Status
General availability:
/purchaseOrders
/purchaseOrders/:purchaseOrderId
Jump To ↓
PurchaseOrderDocument Data Model
Create a Purchase Order
Read all Purchase Orders
Read a Purchase Order
Update a Purchase Order
Delete a Purchase Order
PurchaseOrderDocument Data Model
An object representing a purchase order.
.id (string, required)
The purchase order ID.
.evrythngId (string, read-only)
Standard 24 character EVRYTHNG ID of this purchase order.
.createdAt (integer, read-only)
Timestamp when the resource was created.
.updatedAt (integer, read-only)
Timestamp when the resource was updated.
.version (string)
The latest version of the purchase order.
.status (string, required)
The status of the purchase order, such as 'open' or
'cancelled'.
.purchaser (string)
The name of the purchasing party.
.description (string)
Friendly description of this resource.
.type (string, required)
The type of purchase order determines how the manufacturer
interprets the Order, such as 'stand-alone', 'reorder',
'direct-ship'.
.issueDate (string, required)
The date the purchase order was issued, in YYYY-MM-DD
format.
.parties (array of PurchaseOrderPartyDocument, max. 13, required)
The parties involved in the purchase order. Must contain one
item for each of 'ship-from', 'ship-to', and 'supplier'.
.lines (array of LineItemDocument, max. 1000, required)
Line Items outlining the products, quantities and dates
included in the purchase order.
.tags (array of string)
Array of string tags associated with this resource.
.customFields (CustomFieldsDocument)
Object of case-sensitive key-value pairs of custom fields
associated with the resource.
.identifiers (IdentifiersDocument)
Various identifiers (EPC, GTIN, etc.) as a JSON object with
one or more key-value pairs.
{
"description": "An object representing a purchase order.",
"type": "object",
"required": ["id", "status", "type", "issueDate", "parties", "lines"],
"properties": {
"id": {
"type": "string",
"description": "The purchase order ID."
},
"evrythngId": {
"type": "string",
"description": "Standard 24 character EVRYTHNG ID of this purchase order.",
"readOnly": true
},
"createdAt": {
"type": "integer",
"description": "Timestamp when the resource was created.",
"readOnly": true,
"minimum": 0
},
"updatedAt": {
"type": "integer",
"description": "Timestamp when the resource was updated.",
"readOnly": true,
"minimum": 0
},
"version": {
"description": "The latest version of the purchase order.",
"type": "string",
"example": "1",
"minLength": 1,
"maxLength": 32
},
"status": {
"description": "The status of the purchase order",
"type": "string",
"enum": ["open", "cancelled", "closed"],
"example": "open",
"minLength": 2,
"maxLength": 32
},
"purchaser": {
"description": "The name of the purchasing party.",
"type": "string",
"minLength": 2,
"maxLength": 32
},
"description": {
"type": "string",
"description": "Friendly description of this resource."
},
"type": {
"description": "The type of purchase order determines how the manufacturer interprets the Order, such as 'stand-alone', 'reorder', 'direct-ship'.",
"type": "string",
"example": "stand-alone",
"minLength": 2,
"maxLength": 32
},
"issueDate": {
"description": "The date the purchase order was issued, in YYYY-MM-DD format.",
"type": "string",
"example": "2019-02-10",
"format": "date"
},
"parties": {
"description": "The parties involved in the purchase order. Must contain one item for each of 'ship-from', 'ship-to', and 'supplier'.",
"type": "array",
"example": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"items": {
"description": "A party involved in the purchase order.",
"type": "object",
"additionalProperties": false,
"required": ["id", "type"],
"properties": {
"id": {
"description": "Colon separated identifer, referencing a place.",
"type": "string",
"example": "gs1:414:01251",
"minLength": 2,
"maxLength": 64
},
"type": {
"description": "The role the party has in the purchase order, such as 'ship-from', 'ship-to', 'supplier', 'mark-for'.",
"type": "string",
"enum": ["ship-from", "ship-to", "supplier", "mark-for"],
"example": "ship-from"
}
}
},
"minItems": 2,
"maxItems": 13
},
"lines": {
"description": "Line Items outlining the products, quantities and dates included in the purchase order.",
"type": "array",
"items": {
"description": "A purchase order Line Item.",
"type": "object",
"additionalProperties": false,
"required": ["id", "quantity", "product", "exportDate", "deliveryDate"],
"properties": {
"id": {
"description": "The purchase order Line number.",
"type": "string",
"example": "00010",
"minLength": 2,
"maxLength": 64
},
"quantity": {
"description": "The quantity of products to be manufactured.",
"type": "number",
"example": 100,
"minimum": 0
},
"unitOfMeasure": {
"description": "The unit of measure for the line item such as \"each\".",
"type": "string",
"minLength": 1,
"maxLength": 64,
"default": "each"
},
"product": {
"description": "A colon separated identifier string referencing an EVRYTHNG product.",
"type": "string",
"example": "gs1:01:00000123456789",
"minLength": 3,
"maxLength": 128
},
"exportDate": {
"description": "The date the line item is expected to be exported on, in YYYY-MM-DD format.",
"type": "string",
"example": "2019-02-14",
"format": "date"
},
"deliveryDate": {
"description": "The date the line item is expected to be delivered on, in YYYY-MM-DD format.",
"type": "string",
"example": "2019-02-18",
"format": "date"
}
}
},
"minItems": 1,
"maxItems": 1000
},
"tags": {
"type": "array",
"description": "Array of string tags associated with this resource.",
"items": {
"type": "string",
"maxLength": 60
}
},
"customFields": {
"type": "object",
"description": "Object of case-sensitive key-value pairs of custom fields associated with the resource."
},
"identifiers": {
"type": "object",
"description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
}
},
"x-filterable-fields": [
{
"name": "shipFrom",
"type": "list of string",
"operators": ["="]
},
{
"name": "status",
"type": "list of string",
"operators": ["="]
},
{
"name": "tags",
"type": "list of string",
"operators": ["="]
},
{
"name": "type",
"type": "list of string",
"operators": ["="]
}
]
}
{
"id": "234567890",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
],
"version": "1",
"evrythngId": "U8xtbEasDmbnhagkfsbgbpdr",
"createdAt": 1550143360591,
"updatedAt": 1550143360591
}
See also: PurchaseOrderPartyDocument, LineItemDocument
Filterable Fields
This resource type can be filtered using the following fields and operators.
| Field | Type | Operators |
|---|---|---|
createdAt | Number | =, >, < |
shipFrom | List of string | = |
status | List of string | = |
tags | List of string | = |
type | List of string | = |
updatedAt | Number | =, >, < |
PurchaseOrderPartyDocument Data Model
.id (string, required)
Colon separated identifer, referencing a place.
.type (string, required, one of 'ship-from', 'ship-to', 'supplier', 'mark-for')
The role the party has in the purchase order, such as
'ship-from', 'ship-to', 'supplier', 'mark-for'.
{
"description": "A party involved in the purchase order.",
"type": "object",
"additionalProperties": false,
"required": ["id", "type"],
"properties": {
"id": {
"description": "Colon separated identifer, referencing a place.",
"type": "string",
"example": "gs1:414:01251",
"minLength": 2,
"maxLength": 64
},
"type": {
"description": "The role the party has in the purchase order, such as 'ship-from', 'ship-to', 'supplier', 'mark-for'.",
"type": "string",
"enum": ["ship-from", "ship-to", "supplier", "mark-for"],
"example": "ship-from"
}
}
}
{
"id": "gs1:414:01251",
"type": "ship-from"
}
See also: AddressDocument
LineItemDocument Data Model
A single line item.
.id (string, required)
The purchase order Line number.
.quantity (number, required)
The quantity of products to be manufactured.
.unitOfMeasure (string)
The unit of measure for the line item such as "each".
.product (string, required)
A colon separated identifier string referencing an EVRYTHNG
product.
.exportDate (string, required)
The date the line item is expected to be exported on, in
YYYY-MM-DD format.
.deliveryDate (string, required)
The date the line item is expected to be delivered on, in
YYYY-MM-DD format.
.customFields (CustomFieldsDocument)
Object of case-sensitive key-value pairs of custom fields
associated with the resource.
{
"description": "A purchase order Line Item.",
"type": "object",
"additionalProperties": false,
"required": ["id", "quantity", "product", "exportDate", "deliveryDate"],
"properties": {
"id": {
"description": "The purchase order Line number.",
"type": "string",
"example": "00010",
"minLength": 2,
"maxLength": 64
},
"quantity": {
"description": "The quantity of products to be manufactured.",
"type": "number",
"example": 100,
"minimum": 0
},
"unitOfMeasure": {
"description": "The unit of measure for the line item such as \"each\".",
"type": "string",
"minLength": 1,
"maxLength": 64,
"default": "each"
},
"product": {
"description": "A colon separated identifier string referencing an EVRYTHNG product.",
"type": "string",
"example": "gs1:01:00000123456789",
"minLength": 3,
"maxLength": 128
},
"exportDate": {
"description": "The date the line item is expected to be exported on, in YYYY-MM-DD format.",
"type": "string",
"example": "2019-02-14",
"format": "date"
},
"deliveryDate": {
"description": "The date the line item is expected to be delivered on, in YYYY-MM-DD format.",
"type": "string",
"example": "2019-02-18",
"format": "date"
},
"customFields": {
"type": "object",
"description": "Object of case-sensitive key-value pairs of custom fields associated with the resource."
}
}
}
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
Create a Purchase Order
POST /purchaseOrders
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
PurchaseOrderDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X POST 'https://api.evrythng.com/purchaseOrders' \
-d '{
"id": "234567890",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
]
}'
const payload = {
id: '234567890',
status: 'open',
type: 'stand-alone',
description: 'A purchase order for 100 items',
issueDate: '2019-02-14',
parties: [
{
id: 'gs1:414:943234',
type: 'supplier'
},
{
id: 'gs1:414:01251',
type: 'ship-from'
},
{
id: 'gs1:414:NA0193',
type: 'ship-to'
}
],
lines: [
{
id: '00010',
quantity: 100,
product: 'gs1:01:00000123456789',
exportDate: '2019-02-17',
deliveryDate: '2019-02-20'
}
]
};
operator.purchaseOrder().create(payload)
.then(console.log);
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "234567890",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
],
"version": "1",
"evrythngId": "U8xtbEasDmbnhagkfsbgbpdr",
"createdAt": 1550143360591,
"updatedAt": 1550143360591
}
Read all Purchase Orders
List purchase orders in an account
GET /purchaseOrders
Authorization: $OPERATOR_API_KEY
curl -i \
-H Authorization:$OPERATOR_API_KEY \
-X GET https://api.evrythng.com/purchaseOrders
operator.purchaseOrder().read()
.then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "234567890",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
],
"version": "1",
"evrythngId": "U8xtbEasDmbnhagkfsbgbpdr",
"createdAt": 1550143360591,
"updatedAt": 1550143360591
},
{
"id": "234567891",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 10 items",
"issueDate": "2019-02-01",
"parties": [
{
"id": "gs1:414:92431223",
"type": "supplier"
},
{
"id": "gs1:414:9382392",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 10,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-10",
"deliveryDate": "2019-02-13"
}
],
"createdAt": 1550143360594,
"updatedAt": 1550143360594
}
]
Read a Purchase Order
Purchase Order resources can be read from the API using the id originally supplied in the creation request.
GET /purchaseOrders/:purchaseOrderId
Authorization: $OPERATOR_API_KEY
curl -H "Authorization: $OPERATOR_API_KEY" \
-X GET 'https://api.evrythng.com/purchaseOrders/4700000111'
const purchaseOrderId = '23jh4jjk8';
operator.purchaseOrder(purchaseOrderId).read()
.then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "234567890",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
],
"version": "1",
"createdAt": 1550143360591,
"updatedAt": 1550143360591
}
Update a Purchase Order
Update a Purchase Order by submitting a full update to the original resource. A partial update with a partial payload is possible for the following properties: version, status, purchaser, description, type, issueDate, parties, identifiers, customFields, tags.
PUT /purchaseOrders/:purchaseOrderId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
PurchaseOrderDocument
curl -H "Content-Type: application/json" \
-H "Authorization: $OPERATOR_API_KEY" \
-X PUT 'https://api.evrythng.com/purchaseOrders/234567890' \
-d '{
"id": "234567890",
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20"
}
]
}'
const purchaseOrderId = '23jh4jjk8';
const payload = {
id: '234567890',
status: 'open',
type: 'stand-alone',
description: 'A purchase order for 100 items',
issueDate: '2019-02-14',
parties: [
{
id: 'gs1:414:943234',
type: 'supplier'
},
{
id: 'gs1:414:01251',
type: 'ship-from'
},
{
id: 'gs1:414:NA0193',
type: 'ship-to'
}
],
lines: [
{
id: '00010',
quantity: 100,
product: 'gs1:01:00000123456789',
exportDate: '2019-02-17',
deliveryDate: '2019-02-20'
}
]
};
operator.purchaseOrder(purchaseOrderId).update(payload)
.then(console.log);
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "open",
"type": "stand-alone",
"description": "A purchase order for 100 items",
"issueDate": "2019-02-14",
"parties": [
{
"id": "gs1:414:943234",
"type": "supplier"
},
{
"id": "gs1:414:01251",
"type": "ship-from"
},
{
"id": "gs1:414:NA0193",
"type": "ship-to"
}
],
"lines": [
{
"id": "00010",
"quantity": 100,
"product": "gs1:01:00000123456789",
"exportDate": "2019-02-17",
"deliveryDate": "2019-02-20",
"unitOfMeasure": "each"
}
],
"createdAt": 1553269853427,
"updatedAt": 1553269952396,
"id": "234567890"
}
Delete a Purchase Order
Delete a single Purchase Order by ID.
DELETE /purchaseOrders/:purchaseOrderId
Authorization: $OPERATOR_API_KEY
curl -H "Authorization: $OPERATOR_API_KEY" \
-X DELETE 'https://api.evrythng.com/purchaseOrders/234567890'
const purchaseOrderId = '23jh4jjk8';
operator.purchaseOrder(purchaseOrderId).delete();
HTTP/1.1 204 No Content