ESM Country Clearance Guidelines (EPCIS v1.2)

See How To Use this Guide before interpreting the guidelines below.

Message Type: SOM_ESM_COUNTRY_CLEARANCE

Info Exchange Display Name: ESM Country Clearance

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.
Data Element Occurs
Length		 Type Description
epcis:EPCISDocument [1…1]
[-]		 - Required. EPCIS message root element.
  @schemaVersion [1…1]
[0/*]		 Decimal Required. The version of the EPCIS schema used to populate the EPCIS document elements. Must equal 1.2. *1
  @creationDate [1…1]
[1/*]		 DateTime Required. Date the message was created in YYYY-MM-DDTHH:MM:SS:mmZ format. *2
  EPCISHeader [0…1]
[-]		 - Required. The XML file control header.
    sbdh:StandardBusinessDocumentHeader [1…1]
[-]		 - Required. Business header information including EPCIS Header Version, Sender, and Receiver information, along with the document identification.
      sbdh:HeaderVersion [1…1]
[0/*]		 String Required. Version of the Standard Business Document Header (SBDH). The HeaderVersion must be set to 1.0. *3
      sbdh:Sender [1…*]
[-]		 - Required. A unique identification key for the Sender party of the message, representing the organization that created the standard business document. The Sender element must be used only once with GS1 XML messages.
        sbdh:Identifier [1…1]
[1/*]		 String Required. The value of the Identifier element may be a GLN, SGLN, or any other supported business party type. *4

Send SGLN and all other party types with the GS1-conformant uri prefix, for example:

  • urn:epc:id:sgln:088202.867701.0
  • http://epcis.gs1us.org/hc/dea/loc/10023141
GLNs do not have an urn/http prefix.

See the MDPartyTypeAttributes enumeration list for valid values.
          @Authority [1…1]
[1/*]		 String Required. The sender identifier type. The Authority was previously expected to be set to GLN for GS1 XML messages. An update made in December 2016 changed this to accept additional values. *5

See the MDPartyTypeEnums enumeration list for valid values.
      sbdh:Receiver [1…*]
[-]		 - Required. Indicates a unique identification key for the direct Receiver party of the message, representing the organization that receives the standard business document. The Receiver element is used only once with GS1 XML messages.
        sbdh:Identifier [1…1]
[1/*]		 String Required. The value of the Identifier element may be a GLN, SGLN, or any other supported business party type. *6

Send SGLN and all other party types with the GS1-conformant uri prefix, for example:

  • urn:epc:id:sgln:088202.867701.0
  • http://epcis.gs1us.org/hc/dea/loc/10023141
GLNs do not have an urn/http prefix.

See the MDPartyTypeAttributes enumeration list for valid values.
          @Authority [1…1]
[1/*]		 String Required. The receiver identifier type. The Authority was previously expected to be set to "GLN" for GS1 XML messages. An update made in December 2016 changed this to accept additional values. *7

See the MDPartyTypeEnums enumeration list for valid values.
      sbdh:DocumentIdentification [1…1]
[-]		 - Required. Contains the identification group for the message.
        sbdh:Standard [1…1]
[0/*]		 String Required. Name of the document standard contained in the file or message. The standard value for this field is EPCglobal. *8
        sbdh:TypeVersion [1…1]
[0/*]		 String Required. Reflects the version of the document included. This is the complete version of the document itself and is different from the HeaderVersion as these are hard-coded values. The TypeVersion is set to 1.0. *9
        sbdh:InstanceIdentifier [1…1]
[1/*]		 String Required. Reference information that uniquely identifies this instance of the Standard Business Document between the Sender and the Receiver. This identifier confirms this document as being distinct from others. *10
        sbdh:Type [1…1]
[0/*]		 String Required. Identifies the document type. The Type value is set to "Events" for a shipment event. *11
        sbdh:CreationDateAndTime [1…1]
[0/*]		 DateTime Required. The date and time of the SBDH document's creation. GMT create date and time for the EPCIS message. The system expects the Z to be appended; however, if it is not included, the system assumes that the time is GMT and therefore appends the Z.
  EPCISBody [1…1]
[-]		 - Required. Contains all of the EPCIS events for this message.
    EventList [1…1]
[-]		 - Required. The EventList must include one or more Object Events for country clearance.
      ObjectEvent [1…*]
[-]		 - Required. The ObjectEvent indicates the message type. Indicates a country clearance event when:
  • action = OBSERVE
  • bizStep = urn:epcglobal:cbv:bizstep:inspecting
  • disposition = http://epcis.tracelink.com/disp/cleared_customs
        eventTime [1…1]
[1/*]		 DateTime Required. The time stamp of the date/time when the event occurred in YYYY-MM-DDTHH:MM:SS.mm or YYYY-MM-DDTHH:MM:SS.mmm format. Must include a time zone indicator as specified in Section 9.5 of [EPCIS1.0.1]. The system expects the Z to be appended if it is not included, however, the system assumes that the time is GMT and therefore appends the Z. *12
        eventTimeZoneOffset [1…1]
[1/*]		 String Required. The time zone offset in the place where the event occurred, consistent with what choice was made for eventTime. A time offset is an amount of time subtracted from or added to UTC (Coordinated Universal Time) to get the current civil time, whether it is standard time or Daylight saving time. Per Section 7.2.8 of [EPCIS1.0.1]. *13
        epcList [1…1]
[-]		 - This element group is not mapped. Send an empty tag (i.e. <epcList/>). Serial numbers are mapped from the tl:itemList, tl: homogeneousContainersList, and tl:heterogeneousContainersList element groups in tl:countryClearanceEventExtensions.
        action [1…1]
[0/*]		 String Required. The action type of the event. This value must equal OBSERVE. *14
        bizStep [0…1]
[0/*]		 AnyURI Required. The business step taken in the event. This value must equal urn:epcglobal:cbv:bizstep:inspecting. *15
        disposition [0…1]
[0/*]		 AnyURI

Required. Indicates the status of the message. This value must equal http://epcis.tracelink.com/disp/cleared_customs. *16
        readPoint [0…1]
[-]		 - Required. The SGLN EPC of the location from where the event occurred. This may be a site-level SGLN or a more granular location identifier. For country clearance, this is the importing party identifier.
          id [1…1]
[0/*]		 AnyURI Required. The SGLN EPC of the location from where the event occurred. This may be a site-level SGLN or a more granular location identifier. For country clearance, this is the importing party identifier. *17

See the MDPartyTypeAttributes enumeration list for valid values.
        tl:countryClearanceEventExtensions [0…1]
[-]		 - Main extension body.
          tl:clearanceType [1…1]
[1/*]		 String Required. Identifies the clearance type. *18

See the ClearanceType enumeration list for valid values.
          tl:importFromCountry [1…1]
[1/*]		 String Required. Country the product is being imported from using the standard two-letter abbreviation specified in ISO 3166-1 alpha-2:1997 country code. *19
          tl:importToCountry [1…1]
[1/*]		 String Required. Country the product is being imported into using the standard two-letter abbreviation specified in ISO 3166-1 alpha-2:1997 country code. *20
          tl:registrationDate [0…1]
[0/*]		 Date Conditionally required if tl:clearanceType = CUSTOMS. Registration date in YYYY-MM-DD XML date format. *21
          tl:customsAuthorityCode [0…1]
[0/*]		 String Conditionally required for Russia if tl:clearanceType = CUSTOMS. Customs authority code. *22
          tl:declarationReleaseNumber [0…1]
[0/*]		 String Conditionally required for Russia if tl:clearanceType = CUSTOMS. Declaration release number for product. *23
          tl:actionCode [0…1]
[0/*]		 String Conditionally required for Russia if tl:clearanceType = CUSTOMS. Action code. *24

See the ActionCode enumeration list for valid values.
          tl:importingPartyId [1…1]
[1/*]		 String Required. Importing party identifier. *25
            @type [1…1]
[1/*]		 String Required. Importing party identifier type. *26

See the BusinessAndLocationId enumeration list for valid values.
          tl:itemList [0…1]
[-]		 - Conditionally required if both tl:homogeneousContainersList and tl:heterogeneousContainersList are not present. List of items. Each item is a single product of loose items (e.g. sampled serial numbers).
            tl:items [1…*]
[-]		 - Required. Products that are being imported. One item will be present for each unique product.
              tl:numberList [1…1]
[1/*]		 String Required. Contains the list of serial numbers of eaches.
                tl:serial [1…1]
[1/*]		 String Required. The serial number being imported. Serial number is expressed in the GS1 Application Identifier format without parentheses for the AI keys. AI(01) (21) formatted serial number for GTINs. *27
              tl:customsValue [1…1]
[-]		 Decimal Required. Per unit customs cost for each order item in order item list. *28
                @currencyCode [1…1]
[3/3]		 String Required. Currency ISO code using ISO 4217-2015 format. *29

See the ISOCurrency enumeration list for valid values.
              tl:transactionIdentifier [1…*]
[0/*]		 String The transaction identifier associated with the country clearance. *30
                @type [1…1]
[1/*]		 String Required. The transaction identifier type. *31

See the ClearanceTransactionId enumeration list for valid values.
                @date [1…1]
[-]		 Date Required. Transaction date attribute in YYYY-MM-DD format. *32
          tl:homogeneousContainersList [0…1]
[-]		 - Conditionally required if both tl:itemList and tl:heterogeneousContainersList are not present. List of homogeneous containers. Each container represents one or more batches of the same product.
            tl:homogeneousContainer [1…*]
[-]		 - Required. Cases or pallets containing the same product.
              tl:numberList [1…1]
[1/*]		 String Required. Contains the list of serial numbers of cases or pallets.
                tl:serial [1…*]
[1/*]		 String Required. Contains the serial number or numbers that are being imported. Serial number expressed in the GS1 Application Identifier format without parenthesis for the AI keys. AI(00) formatted serial number for SSCCs. *33
              tl:customsValue [1…1]
[0/*]		 Decimal Required. Per unit customs cost for each order item in order item list. *34
                @currencyCode [1…1]
[3/3]		 String Required. Currency ISO code using ISO 4217-2015 format. *35

See the ISOCurrency enumeration list for valid values.
              tl:transactionIdentifier [1…*]
[0/*]		 String The transaction identifier associated with the country clearance. *36
                @type [1…1]
[1/*]		 String Required. The transaction identifier type. *37

See the ClearanceTransactionId enumeration list for valid values.
                @date [1…1]
[-]		 Date Required. Transaction date attribute. *38
          tl:heterogeneousContainersList [0…1]
[-]		 - Conditionally required if both tl:itemList and tl:homogeneousContainersList are not present. List of heterogeneous containers. Every container is a case or pallet with different products inside.
            tl:heterogeneousContainer [1…*]
[-]		 - Required. Case or pallet containing a mix of different products.
              tl:serial [1…1]
[1/*]		 String Required. Contains the serial number or numbers that are being imported. Serial number expressed in the GS1 Application Identifier format without parentheses for the AI keys. AI(00) formatted serial number for SSCCs. *39
              tl:containerContents [1…*]
[-]		 - Required. Contents of heterogeneous containers.
                tl:packagingItemCode [1…1]
[1/*]		 String Required. The packaging level item code (e.g. GTIN-14, CN-ResCode) associated with the serialized items that are being imported. *40
                  @type [1…1]
[1/*]		 String Required. The product code type for the packaging item code. *41

See the ItemCode enumeration list for valid values.
                cbvmda:lotNumber [1…1]
[1/*]		 String Required. The lot number associated with the specified serial numbers used to identify the serial numbers that are being updated. *42
                tl:customsValue [1…1]
[0/*]		 Decimal Required. Per unit customs cost for each order item in order item list. *43
                  @currencyCode [1…1]
[3/3]		 String Required. Currency ISO code using ISO 4217-2015 format. *44

See the ISOCurrency enumeration list for valid values.
                tl:transactionIdentifier [1…*]
[0/*]		 String The transaction identifier(s) associated with the country clearance, if available. *45
                  @type [1…1]
[1/*]		 String Required. The transaction identifier type. *46

See the ClearanceTransactionId enumeration list for valid values.
                  @date [1…1]
[-]		 Date Required. Transaction date attribute. *47