Shipment Notices

📘
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 Shipment Notice API allows solution developers to record their shipment notice documents (similar to Advance Shipment Notices) within an EVRYTHNG account, enabling coordinated functionality with the Purchase Orders API. A shipment notice resource details a shipment to be sent, including type, container contents, and important dates.

When reading, updating, or deleting a shipment notice, either the id or asnId property may be used.

API Status
Beta:
/shipmentNotices
/shipmentNotices/{shipmentNoticeId}

Jump To ↓

ShipmentNoticeDocument Data Model
Create a shipment notice
Read all shipment notice
Read a shipment notice
Update a shipment notice
Delete a shipment notice

ShipmentNoticeDocument Data Model

An object representing a shipment notice.

.id (string, read-only)
    The ID of this resource.

.asnId (string, required)
    ID of the associated shipment notice.

.description (string)
    Friendly description of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.tags (array of string)
    Array of string tags associated with this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve 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.

.version (string)
    Identifies the current version of the shipment, the default
    value is '1'

.status (string, required, one of 'open', 'closed', 'cancelled')
    The status of the shipment

.purchaseOrderId (string)
    A reference to an associated purchase order, applies to all contents   
    if specified

.issueDate (string, required)
    The date the shipment was issued on

.deliveryDate (string)
    The date the shipment is due to be delivered

.transportation (string)
    The type of transportation

.parties (array of ShipmentNoticePartyDocument, max. 3, required)
    The parties involved in the shipment

.contents (array of ShipmentNoticeContentDocument, max. 1000)
    Array of products in the shipment and their quantites.

{
  "description": "An object representing a shipment notice.",
  "type": "object",
  "required": ["asnId", "status", "issueDate", "parties"],
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "asnId": {
      "type": "string",
      "description": "ID of the associated shipment notice.",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9._:+-]+$",
      "example": "9827429837429823828273"
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "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
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve 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."
    },
    "version": {
      "description": "Identifies the current version of the shipment, the default value is '1'",
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "default": 1,
      "example": "1"
    },
    "status": {
      "type": "string",
      "description": "The status of the shipment",
      "enum": ["open", "closed", "cancelled"],
      "default": "open",
      "example": "open"
    },
    "purchaseOrderId": {
      "description": "A reference to an associated purchase order, applies to all contents if specified",
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-zA-Z0-9:_+.@-]+$",
      "example": "4700990774"
    },
    "issueDate": {
      "description": "The date the shipment was issued on",
      "type": "string",
      "format": "date-time",
      "example": "2016-12-19T16:39:57-08:00"
    },
    "deliveryDate": {
      "description": "The date the shipment is due to be delivered",
      "type": "string",
      "format": "date-time",
      "example": "2013-04-12T23:20:50.52Z"
    },
    "transportation": {
      "type": "string",
      "description": "The type of transportation",
      "minLength": 1,
      "maxLength": 32,
      "example": "Air"
    },
    "parties": {
      "type": "array",
      "description": "The parties involved in the shipment",
      "minItems": 2,
      "maxItems": 3,
      "items": {
        "description": "A party involved in this shipment notice.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Colon separated identifier with format of 'type:value'",
            "example": "gs1:01:0200010901",
            "minLength": 3,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+:[A-Za-z0-9._-]+$"
          },
          "name": {
            "type": "string",
            "description": "Display name for the party",
            "minLength": 2,
            "maxLength": 128
          },
          "type": {
            "type": "string",
            "description": "The party type defines what involvement the identified party has in this shipment notice",
            "enum": ["ship-from", "ship-to", "bill-to"],
            "example": "ship-from"
          },
          "identifiers": {
            "type": "object",
            "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
          },
          "address": {
            "additionalProperties": false,
            "type": "object",
            "description": "An object representing a street address.",
            "properties": {
              "extension": {
                "type": "string",
                "description": "The extension of the address."
              },
              "street": {
                "type": "string",
                "description": "The street of the address."
              },
              "postalCode": {
                "type": "string",
                "description": "The postal code of the address."
              },
              "city": {
                "type": "string",
                "description": "The city of the address."
              },
              "county": {
                "type": "string",
                "description": "The county of the address."
              },
              "state": {
                "type": "string",
                "description": "The state of the address."
              },
              "country": {
                "type": "string",
                "description": "The country of the address."
              },
              "countryCode": {
                "type": "string",
                "description": "The country code of the address."
              },
              "district": {
                "type": "string",
                "description": "The district of the address."
              },
              "buildingName": {
                "type": "string",
                "description": "The building name of the address."
              },
              "buildingFloor": {
                "type": "string",
                "description": "The building floor of the address."
              },
              "buildingRoom": {
                "type": "string",
                "description": "The building room of the address."
              },
              "buildingZone": {
                "type": "string",
                "description": "The building zone of the address."
              },
              "crossing1": {
                "type": "string",
                "description": "The first crossing of the address."
              },
              "crossing2": {
                "type": "string",
                "description": "The second crossing of the address."
              }
            }
          }
        }
      },
      "example": [
        {
          "id": "gs1:414:01251",
          "type": "ship-from"
        },
        {
          "name": "The Landmark, Shop No. G14",
          "type": "ship-to",
          "address": {
            "street": "113-114, Central",
            "city": "Hong Kong"
          }
        }
      ]
    },
    "contents": {
      "type": "array",
      "description": "Array of products in the shipment and their quantites.",
      "items": {
        "description": "A product included in this shipment notice.",
        "type": "object",
        "additionalProperties": false,
        "required": ["product", "quantity"],
        "properties": {
          "product": {
            "type": "string",
            "description": "The product identifier. Colon separated identifier with format of 'type:value'",
            "example": "gs1:01:0200010901",
            "minLength": 3,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+:[A-Za-z0-9._-]+$"
          },
          "quantity": {
            "type": "integer",
            "description": "The quantity of this product included in this shipment.",
            "minimum": 1,
            "maximum": 9999999,
            "example": 250
          }
        }
      },
      "minItems": 1,
      "maxItems": 1000,
      "example": [
        {
          "product": "gs1:01:00001254563898",
          "quantity": 250
        },
        {
          "product": "gs1:01:00283679123844",
          "quantity": 42
        }
      ]
    }
  },
  "x-filterable-fields": [
    {
      "name": "purchaseOrderId",
      "type": "string",
      "operators": []
      ]
    },
    {
      "name": "tags",
      "type": "list of string",
      "operators": []
      ]
    }
  ]
}

{
  "id": "Un9MbDrTBXsatpawwkbDRHdb",
  "asnId": "9827429837429823828273",
  "version": "1",
  "purchaseOrderId": "4700990774",
  "issueDate": "2019-06-19T16:39:57-08:00",
  "transportation": "Expedited Freight",
  "parties": [
    {
      "id": "gs1:414:01251",
      "type": "ship-from"
    },
    {
      "name": "The Landmark, Shop No. G14",
      "type": "ship-to",
      "address": {
        "street": "113-114, Central",
        "city": "Hong Kong"
      }
    }
  ],
  "contents": [
    {
      "product": "gs1:01:00001254563898",
      "quantity": 250
    },
    {
      "product": "gs1:01:00283679123844",
      "quantity": 42
    }
  ],
  "tags": [
    "ongoing",
    "important",
    "access-all"
  ],
  "createdAt": 1550143360591,
  "updatedAt": 1550143360591
}

Filterable Fields

This resource type can be filtered using the following fields and operators.

Field	Type	Operators
`purchaseOrderId`	String	`=`
`tags`	List of string	`=`
`status`	List of string	`=`

ShipmentNoticePartyDocument Data Model

A party involved in this shipment notice.

.id (string)
    Colon separated identifier with format of 'type:value'

.name (string)
    Display name for the party

.type (string, one of 'ship-from', 'ship-to', 'bill-to')
    The party type defines what involvement the identified party 
    has in this shipment notice

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

.address (AddressDocument)
    An object representing a street address.

{
  "description": "A party involved in this shipment notice.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "Colon separated identifier with format of 'type:value'",
      "example": "gs1:01:0200010901",
      "minLength": 3,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+:[A-Za-z0-9._-]+$"
    },
    "name": {
      "type": "string",
      "description": "Display name for the party",
      "minLength": 2,
      "maxLength": 128
    },
    "type": {
      "type": "string",
      "description": "The party type defines what involvement the identified party has in this shipment notice",
      "enum": ["ship-from", "ship-to", "bill-to"],
      "example": "ship-from"
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "address": {
      "additionalProperties": false,
      "type": "object",
      "description": "An object representing a street address.",
      "properties": {
        "extension": {
          "type": "string",
          "description": "The extension of the address."
        },
        "street": {
          "type": "string",
          "description": "The street of the address."
        },
        "postalCode": {
          "type": "string",
          "description": "The postal code of the address."
        },
        "city": {
          "type": "string",
          "description": "The city of the address."
        },
        "county": {
          "type": "string",
          "description": "The county of the address."
        },
        "state": {
          "type": "string",
          "description": "The state of the address."
        },
        "country": {
          "type": "string",
          "description": "The country of the address."
        },
        "countryCode": {
          "type": "string",
          "description": "The country code of the address."
        },
        "district": {
          "type": "string",
          "description": "The district of the address."
        },
        "buildingName": {
          "type": "string",
          "description": "The building name of the address."
        },
        "buildingFloor": {
          "type": "string",
          "description": "The building floor of the address."
        },
        "buildingRoom": {
          "type": "string",
          "description": "The building room of the address."
        },
        "buildingZone": {
          "type": "string",
          "description": "The building zone of the address."
        },
        "crossing1": {
          "type": "string",
          "description": "The first crossing of the address."
        },
        "crossing2": {
          "type": "string",
          "description": "The second crossing of the address."
        }
      }
    }
  }
}

{
  "name": "The Landmark, Shop No. G14",
  "type": "ship-to",
  "address": {
    "street": "113-114, Central",
    "city": "Hong Kong"
  }
}

ShipmentNoticeContentDocument Data Model

A product included in this shipment notice.

.product (string, required)
    The product identifier. Colon separated identifier with 
    format of 'type:value'

.quantity (integer, required)
    The quantity of this product included in this shipment.
    
.purchaseOrderId (string)
    A reference to an associated purchase order, cannot co-exist with a 
    purchase order id that has been defined in the shipment notice

{
  "description": "A product included in this shipment notice.",
  "type": "object",
  "additionalProperties": false,
  "required": ["product", "quantity"],
  "properties": {
    "product": {
      "type": "string",
      "description": "The product identifier. Colon separated identifier with format of 'type:value'",
      "example": "gs1:01:0200010901",
      "minLength": 3,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+:[A-Za-z0-9._-]+$"
    },
    "quantity": {
      "type": "integer",
      "description": "The quantity of this product included in this shipment.",
      "minimum": 1,
      "maximum": 9999999,
      "example": 250
    },
    "purchaseOrderId": {
      "type": "string",
      "description": "A reference to an associated purchase order, cannot co-exist with a purchase order id that has been defined in the shipment notice",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-zA-Z0-9:_+.@-]+$",
      "example": "4700990774"
    }
  }
}

{
  "product": "gs1:01:00001254563898",
  "quantity": 250
}

Create a shipment notice

Create a new shipment notice resource.

POST /shipmentNotices
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ShipmentNoticeDocument

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.com/shipmentNotices \
  -d '{
  "asnId": "9827429837429823828273",
  "version": "1",
  "purchaseOrderId": "4700990774",
  "issueDate": "2019-06-19T16:39:57-08:00",
  "transportation": "Expedited Freight",
  "parties": [
    {
      "id": "gs1:414:01251",
      "type": "ship-from"
    },
    {
      "name": "The Landmark, Shop No. G14",
      "type": "ship-to",
      "address": {
        "street": "113-114, Central",
        "city": "Hong Kong"
      }
    }
  ],
  "contents": [
    {
      "product": "gs1:01:00001254563898",
      "quantity": 250
    },
    {
      "product": "gs1:01:00283679123844",
      "quantity": 42
    }
  ],
  "tags": [
    "ongoing",
    "important",
    "access-all"
  ]
}'

const payload = {
  asnId: '9827429837429823828273',
  version: '1',
  purchaseOrderId: '4700990774',
  issueDate: '2019-06-19T16:39:57-08:00',
  transportation: 'Expedited Freight',
  parties: [
    {
      id: 'gs1:414:01251',
      type: 'ship-from'
    },
    {
      name: 'The Landmark, Shop No. G14',
      type: 'ship-to',
      address: {
        street: '113-114, Central',
        city: 'Hong Kong'
      }
    }
  ],
  contents: [
    {
      product: 'gs1:01:00001254563898',
      quantity: 250
    },
    {
      product: 'gs1:01:00283679123844',
      quantity: 42
    }
  ],
  tags: [
    'ongoing',
    'important',
    'access-all'
  ]
};

operator.shipmentNotice().create(payload)
  .then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "Un9MbDrTBXsatpawwkbDRHdb",
  "asnId": "9827429837429823828273",
  "version": "1",
  "purchaseOrderId": "4700990774",
  "issueDate": "2019-06-19T16:39:57-08:00",
  "transportation": "Expedited Freight",
  "parties": [
    {
      "id": "gs1:414:01251",
      "type": "ship-from"
    },
    {
      "name": "The Landmark, Shop No. G14",
      "type": "ship-to",
      "address": {
        "street": "113-114, Central",
        "city": "Hong Kong"
      }
    }
  ],
  "contents": [
    {
      "product": "gs1:01:00001254563898",
      "quantity": 250
    },
    {
      "product": "gs1:01:00283679123844",
      "quantity": 42
    }
  ],
  "tags": [
    "ongoing",
    "important",
    "access-all"
  ],
  "createdAt": 1550143360591,
  "updatedAt": 1550143360591
}

Read all shipment notices

Read all shipment notices in an account.

GET /shipmentNotices
Authorization: $OPERATOR_API_KEY

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.com/shipmentNotices

operator.shipmentNotice().read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "asnId": "9827429837429823828273",
    "id": "Un9MbDrTBXsatpawwkbDRHdb",
    "version": "1",
    "purchaseOrderId": "4700990774",
    "issueDate": "2019-06-19T16:39:57-08:00",
    "transportation": "Expedited Freight",
    "parties": [
      {
        "id": "gs1:414:01251",
        "type": "ship-from"
      },
      {
        "name": "The Landmark, Shop No. G14",
        "type": "ship-to",
        "address": {
          "street": "113-114, Central",
          "city": "Hong Kong"
        }
      }
    ],
    "tags": [
      "ongoing",
      "important",
      "access-all"
    ],
    "createdAt": 1550143360591,
    "updatedAt": 1550143360591
  },
  {
    "asnId": "ASN:39842734:FASSLK",
    "id": "UrVeSHdrBD8a9pwwRpHVAnYf",
    "version": "12",
    "purchaseOrderId": "5230917486",
    "issueDate": "2018-05-13T12:00:00-03:00",
    "transportation": "Truckload",
    "createdAt": 1550143360591,
    "updatedAt": 1550143360591,
    "parties": [
      {
        "id": "factory:23048273",
        "type": "ship-from"
      },
      {
        "name": "GREOLE HUB",
        "type": "ship-to",
        "address": {
          "country": "CN",
          "latitude": 43.493847983,
          "longitude": 56.342948273
        }
      },
      {
        "name": "GREOLE TRST. Co.",
        "type": "bill-to",
        "address": {
          "country": "CN",
          "latitude": 43.837298364,
          "longitude": 56.4998243
        }
      }
    ]
  }
]

Read a shipment notice

Read a shipment notice resource.

GET /shipmentNotices/:shipmentNoticeId
Authorization: $OPERATOR_API_KEY

curl -i -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.com/shipmentNotices/:shipmentNoticeId

const shipmentNoticeId = 'UnghCKffVg8a9KwRwE5C9qBs';

operator.shipmentNotice(shipmentNoticeId).read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "Un9MbDrTBXsatpawwkbDRHdb",
  "asnId": "9827429837429823828273",
  "version": "1",
  "purchaseOrderId": "4700990774",
  "issueDate": "2019-06-19T16:39:57-08:00",
  "transportation": "Expedited Freight",
  "parties": [
    {
      "id": "gs1:414:01251",
      "type": "ship-from"
    },
    {
      "name": "The Landmark, Shop No. G14",
      "type": "ship-to",
      "address": {
        "street": "113-114, Central",
        "city": "Hong Kong"
      }
    }
  ],
  "tags": [
    "ongoing",
    "important",
    "access-all"
  ],
  "createdAt": 1550143360591,
  "updatedAt": 1550143360591
}

Update a shipment notice

Update a shipment notice resource.

🚧
Replacement Operation
Updating a shipment notice with a PUT request is a replacement operation - the whole new version of the shipment notice must be provided.

PUT /shipmentNotices/:shipmentNoticeId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ShipmentNoticeDocument (partial)

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X PUT https://api.evrythng.com/shipmentNotices/:shipmentNoticeId \
  -d '{
  "asnId": "9827429837429823828273",
  "version": "2",
  "purchaseOrderId": "4700990774",
  "issueDate": "2019-06-19T16:39:57-08:00",
  "transportation": "Expedited Freight",
  "parties": [
    {
      "id": "gs1:414:01251",
      "type": "ship-from"
    },
    {
      "name": "The Landmark, Shop No. G14",
      "type": "ship-to",
      "address": {
        "street": "113-114, Central",
        "city": "Hong Kong"
      }
    }
  ],
  "tags": [
    "ongoing",
    "important",
    "access-all"
  ]
}'

const shipmentNoticeId = 'UnghCKffVg8a9KwRwE5C9qBs';
const payload = {
  asnId: '9827429837429823828273',
  version: '2',
  purchaseOrderId: '4700990774',
  issueDate: '2019-06-19T16:39:57-08:00',
  transportation: 'Expedited Freight',
  parties: [
    {
      id: 'gs1:414:01251',
      type: 'ship-from'
    },
    {
      name: 'The Landmark, Shop No. G14',
      type: 'ship-to',
      address: {
        street: '113-114, Central',
        city: 'Hong Kong'
      }
    }
  ],
  tags: [
    'ongoing',
    'important',
    'access-all'
  ]
};

operator.shipmentNotice(shipmentNoticeId).update(payload)
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "Un9MbDrTBXsatpawwkbDRHdb",
  "asnId": "9827429837429823828273",
  "version": "2",
  "purchaseOrderId": "4700990774",
  "issueDate": "2019-06-19T16:39:57-08:00",
  "transportation": "Expedited Freight",
  "parties": [
    {
      "id": "gs1:414:01251",
      "type": "ship-from"
    },
    {
      "name": "The Landmark, Shop No. G14",
      "type": "ship-to",
      "address": {
        "street": "113-114, Central",
        "city": "Hong Kong"
      }
    }
  ],
  "tags": [
    "ongoing",
    "important",
    "access-all"
  ],
  "createdAt": 1550143360591,
  "updatedAt": 1550143860591
}

Delete a shipment notice

Delete a shipment notice resource.

DELETE /shipmentNotices/:shipmentNoticeId
Authorization: $OPERATOR_API_KEY

curl -i -H Authorization:$OPERATOR_API_KEY \
  -X DELETE https://api.evrythng.com/shipmentNotices/:shipmentNoticeId

const shipmentNoticeId = 'UnghCKffVg8a9KwRwE5C9qBs';

operator.shipmentNotice(shipmentNoticeId).delete();

Shipment Notices

📘
Enterprise Feature

ShipmentNoticeDocument Data Model

Filterable Fields

ShipmentNoticePartyDocument Data Model

ShipmentNoticeContentDocument Data Model

Create a shipment notice

Read all shipment notices

Read a shipment notice

Update a shipment notice

🚧
Replacement Operation

Delete a shipment notice

📘Enterprise Feature

ShipmentNoticeDocument Data Model

Filterable Fields

ShipmentNoticePartyDocument Data Model

ShipmentNoticeContentDocument Data Model

Create a shipment notice

Read all shipment notices

Read a shipment notice

Update a shipment notice

🚧Replacement Operation

Delete a shipment notice

📘
Enterprise Feature

🚧
Replacement Operation