Shipment Notice

Shipment Notices (also known as Advance Ship Notices or ASNs, or "despatch advice") communicate the details of an outbound shipment from a supplier to a recipient, including what is being shipped, from where, to where, and when it is expected to arrive. Relevant if you are using legacy EDI ASN communication and want to reference this in EPCIS messages or in analytics and rules.

The shipment_notice Object

Field Name	Type	Description
id	uuid	Primary key for the shipment notice.
user_created	object	User who created the record. Read-only.
date_created	datetime	Timestamp in ISO 8601 when the record was created. Read-only.
user_updated	object	User who last updated the record. Read-only.
date_updated	datetime	Timestamp in ISO 8601 when the record was last updated. Read-only.
status	string	Current status of the shipment notice. One of: draft, shipped, delivered, superseded, cancelled.
ship_notice_number	string	Human-readable shipment notice number or reference.
urn	string	Uniform Resource Name uniquely identifying this shipment notice, for use in EPCIS messages (typically auto created by system).
ship_notice_issuer	object	Organisation that issued this shipment notice.
ship_from_organisation	object	Organisation from which the goods are being shipped.
ship_from_location	object	Location from which the goods are being shipped.
ship_to_organisation	object	Organisation receiving the shipment.
ship_to_location	object	Location to which the goods are being delivered.
ship_date	datetime	Date and time the shipment departed.
estimated_arrival_date	datetime	Estimated date and time of arrival at the destination.
carrier_name	string	Name of the carrier or logistics provider.
tracking_number	string	Carrier tracking number for the shipment.
line_items	array of objects	Line items detailing the products and quantities included in the shipment.

---

Sub-Objects

User Object (user_created, user_updated)

See Users for the full schema.

Organisation Object (ship_notice_issuer, ship_from_organisation, ship_to_organisation)

See Organisation for the full schema.

Location Object (ship_from_location, ship_to_location)

See Location for the full schema.

Shipment Notice Line Item (line_items)

Field	Type	Description
id	uuid	Primary key of the line item.
user_created	object	User who created the line item. Read-only.
date_created	datetime	When the line item was created. Read-only.
user_updated	object	User who last updated the line item. Read-only.
date_updated	datetime	When the line item was last updated. Read-only.
ship_notice_id	uuid	Reference to the parent shipment notice.
po_line_item_id	object	Reference to the corresponding Purchase Order line item, if applicable.
product	object	Product being shipped. Links to Product.
quantity_shipped	number	Quantity of the product included in this shipment.
package_id	string	Identifier for the package or container this line item is in.
lot_number	string	Lot or batch number of the shipped product.
expiry_date	string	Expiry date of the product (ISO 8601 date, e.g. 2025-12-31).

---

List Shipment Notices

REST

GET /items/shipment_notice

GraphQL

query {
  shipment_notice {
    id
    status
    ship_notice_number
    ship_date
    estimated_arrival_date
    ship_from_organisation {
      id
      organisation_name
    }
    ship_to_organisation {
      id
      organisation_name
    }
    ship_to_location {
      id
      location_name
    }
    line_items {
      id
      product {
        id
        product_name
      }
      quantity_shipped
    }
  }
}

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit shipment notice objects. If no items are available, data will be an empty array.

---

Retrieve a Shipment Notice

REST

GET /items/shipment_notice/:id

GraphQL

query {
  shipment_notice_by_id(id: "shipment_notice_id") {
    id
    status
    ship_notice_number
    urn
    ship_date
    estimated_arrival_date
    carrier_name
    tracking_number
    ship_notice_issuer {
      id
      organisation_name
    }
    ship_from_organisation {
      id
      organisation_name
    }
    ship_from_location {
      id
      location_name
    }
    ship_to_organisation {
      id
      organisation_name
    }
    ship_to_location {
      id
      location_name
    }
    line_items {
      id
      product {
        id
        product_name
      }
      quantity_shipped
      lot_number
      expiry_date
      package_id
    }
  }
}

Returns

Returns a shipment notice object if a valid primary key was provided.

---

Create a Shipment Notice

REST

POST /items/shipment_notice

{
  "ship_notice_number": "ASN-2024-001",
  "status": "shipped",
  "ship_notice_issuer": "org-uuid",
  "ship_from_organisation": "supplier-org-uuid",
  "ship_from_location": "warehouse-location-uuid",
  "ship_to_organisation": "buyer-org-uuid",
  "ship_to_location": "destination-location-uuid",
  "ship_date": "2024-03-15T08:00:00Z",
  "estimated_arrival_date": "2024-03-18T17:00:00Z",
  "carrier_name": "FedEx",
  "tracking_number": "123456789012"
}

GraphQL

mutation {
  create_shipment_notice_item(data: {
    ship_notice_number: "ASN-2024-001"
    status: "shipped"
    ship_notice_issuer: "org-uuid"
    ship_from_organisation: "supplier-org-uuid"
    ship_from_location: "warehouse-location-uuid"
    ship_to_organisation: "buyer-org-uuid"
    ship_to_location: "destination-location-uuid"
    ship_date: "2024-03-15T08:00:00Z"
    estimated_arrival_date: "2024-03-18T17:00:00Z"
    carrier_name: "FedEx"
    tracking_number: "123456789012"
  }) {
    id
    ship_notice_number
    status
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial shipment notice object.

Returns

Returns the shipment notice object for the created record.

---

Update a Shipment Notice

REST

PATCH /items/shipment_notice/:id

{
  "status": "delivered",
  "tracking_number": "123456789012"
}

GraphQL

mutation {
  update_shipment_notice_item(id: "shipment_notice_id", data: {
    status: "delivered"
    tracking_number: "123456789012"
  }) {
    id
    status
    tracking_number
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial shipment notice object.

Returns

Returns the shipment notice object for the updated record.

---

Delete a Shipment Notice

REST

DELETE /items/shipment_notice/:id

GraphQL

mutation {
  delete_shipment_notice_item(id: "shipment_notice_id") {
    id
  }
}

Returns

Empty body.