Purchase Orders

📘
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
}

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"
}

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

📘Enterprise Feature

PurchaseOrderDocument Data Model

Filterable Fields

PurchaseOrderPartyDocument Data Model

LineItemDocument Data Model

Create a Purchase Order

Read all Purchase Orders

Read a Purchase Order

Update a Purchase Order

Delete a Purchase Order

📘
Enterprise Feature