Purchase Order - JSON Specifiction

Summary

Use this format to send purchase orders to Chain.io or to receive them from Chain.io with the “Chain.io Order JSON” document type.

Some fields, like earliest_delivery_date, are available at both the Header and Line levels. In the event that value is provided at both levels, the Line level value should be used.

Objects

Name	Description
Root	The top level document
Order	A Purchase Order
OrderLine	A line on a purchase order.
Address	A physical location.
Costing Component	A further breakdown of the purchase order line into individual costing components.
Attachment	A file attachment
Container	A container used to ship goods
Order Container	A container used to ship goods
Planned Shipment Legs	A planned shipment leg associated to an order
Planned Shipment Custom Declaration	A planned shipment custom declaration associated to an order
Planned Shipments	A planned shipment associated to an order
Milestones	A milestone associated to an order
Order Native Reference Numbers	A reference number associated to an order
Notes	A note associated to an order
Native Reference Numbers	A reference number associated to an order

Root top

Name	Data Type	Description
`doc_type`	String	Always `chainio_purchase_order`
`orders`	Array<Order>	Array of orders
`version`	String	The version of the specification being used.

Order top

Name	Data Type	Description	Required
`addresses`	Array<Address>	Addresses related to the purhcase order. Valid types are `buyer`, `supplier`, `freight_forwarder`, `ultimate_consignee`, `carrier`, `customs_broker`, `buying-agent`, `consignee`, `manufacturer`, `ship_to`, `consignor`, `sending_forwarder`, `receiving_forwarder`, `carrier`, `goods_available_at`.
`booking_confirmation_date`	DateTime	The date on which the purchase orders have been confirmed for booking by the service provider (the forwarder or NVOCC if not a direct carrier booking) prior to shipment booking.
`booking_confirmation_number`	String	The booking confirmation number from the service provider.
`brand_code`	String	Code for the purchasing party's brand.
`cancelled`	Boolean	When true, the PO is cancelled.
`containerization_type`	String	The type of containerization for the purchase order.
`containers`	Array<Order Container>	Array of containers
`created_at`	DateTime	Timestamp of the time this node was created.
`currency`	String	The 3 character ISO 4217 currency code for the currency that will be used for values on the purchase order. Like “EUR”, “USD”.
`currency_description`	String	A long description of the currency like “Euros” or “US Dollars”.
`customer_id`	String	The supplier's identifier for the purchasing company.
`customer_name`	String	The name of the customer associated with the order.
`customer_order_number`	String	The order number from the party issuing the purchase order.	YES
`department_code`	String	The purchasing company's department number that is responsible for issuing the purchase order.
`department_code_description`	String	Description of the customers department responsible for the order.
`earliest_delivery_date`	DateTime	The earliest moment the supplier may deliver the product to the customer without penalty.
`earliest_in_dc_date`	DateTime	The earliest date which the shipment should be delivered.
`exchange_currency`	String	The currency in which the purchase order was or will be placed.
`exchange_rate`	Decimal	The exchange rate for calculating the exchange currency.
`exworks_required_date`	DateTime	The date on which the product should be ready for pickup.
`first_sale`	Boolean	Whether the first sale rule is applicable when clearing customs
`follow_up_date`	DateTime	The date on which the purchase order should be followed up.
`general_goods_description`	String	General description of the goods on the purchase order.
`inco_term`	String	The Incoterm under which the product will be purchased.
`inco_term_description`	String	The description of the INCO Term under which the product will be purchased.
`inco_term_named_place`	String	The place at which the Incoterm will be fulfilled. For example, the port for an FOB shipment.
`inspection_passed_date`	DateTime	Date/time when the order passed inspection.
`inspection_required`	Boolean	Is an inspection of the product required before shipping?
`instructions`	String	Instructions from the purchasing party to the supplier.
`interchange_control_number`	String	The sequential identifier sent on an EDI document from a trading partner.
`invoice_date`	DateTime	The date on which the invoice was issued.
`latest_delivery_date`	DateTime	The last moment the supplier may deliver the product to the customer without penalty.
`latest_in_dc_date`	DateTime	The latest date which the shipment should be delivered.
`latest_in_store_date`	DateTime	The latest date on which the product should be in store.
`master_order_number`	String	The purchasing party's master order number for the purchase order.
`milestones`	Array<Milestones>	Array of milestones
`mode`	String	The mode of transportation for the purchase order.
`native_reference_numbers`	Array<Order Native Reference Numbers>	Array of native reference numbers
`notes`	Array<Notes>	Array of notes
`order_date`	DateTime	The date and time that the order was issued by the purchasing party.
`order_lines`	Array<OrderLine>	The lines on the order.
`order_type_code`	String	Code of the order type
`order_type_description`	String	Description of the order type
`payment_term`	String	The terms of the payment like NET30, COD, etc.
`payment_term_description`	String	A longer description of the payment term. Like “Cash on Delivery”.
`planned_equipment_type`	String	The type of container / trailer in which the order should be sent.
`planned_shipments`	Array<Planned Shipments>	Array of planned shipments
`promotion_start_date`	String	The date/time when the promotion and advertising for the product in this purchase order will start.
`purchaser_notes`	String	Private notes that are only visible to the purchasing party and owner.
`sales_order_number`	String	The identifying number on the Sales Order issued by the supplier.
`season`	String	The target retail season for the goods on the purchase order. Generally consists of an identifier like 'Summer 2021 ' or 'Black Friday 2021'.
`season_type`	String	Describes the type of season indicated in the season field. Ex. 'Adhoc' or 'Catalogue'
`secondary_order_number`	String	An alternate purchase order identification number in addition to the the customer's order number and supplier's order number. This may be a number representing the purchase order in a secondary purchasing system or a supply chain tool.
`seller_order_number`	String	DEPRECATED: Use supplier_order_number instead.
`sent_date`	String	Time the record was sent by the source system.
`service_level_code`	String	The service level code for the purchase order.
`service_level_description`	String	The service level description for the purchase order.
`ship_from_country`	String	The country from which the goods are shipped.
`ship_from_country_name`	String	The name of the country from which the goods are shipped.
`source_system_id`	String	Record identifier in the system that hosts the master copy of this record.
`status_code`	String	Status code for the purchase order.
`status_description`	String	Description of the status of the purchase order.
`supplier_confirmation_date`	DateTime	The date on which the purchase orders have been confirmed by the supplier.
`supplier_id`	String	The purchasing company's identifier for the company that is supplying the product.
`supplier_name`	String	The name of the supplier.
`supplier_order_number`	String	An additional order number beyond the customer_order_number assigned by the supplier.
`terms_and_conditions`	String	The legal terms and conditions specific to the order. This may be a reference to an external document.
`transaction_purpose_code`	String	The purpose of the transaction. For example, the code could indicate that it is an original, a cancellation of a previously-submitted purchase order, or a duplicate of a previously-submitted purchase order.
`transaction_type_code`	String	The type code of the transaction in relation to the purchase order.
`transmission_uid`	String	A one-time unique identifying code for this transmission of the purchase order in question. Used for tracing and logging purposes.
`warehouse_pick_ticket`	String	Pick ticket number to be used in warehouse.

OrderLine top

Name	Data Type	Description
`actual_in_dc_date`	DateTime	The actual date the product arrived at the distribution center
`addresses`	Array<Address>	Addresses related to the line. Valid types are `shipTo`, `ship_to_store`, `ship_from`, `ultimate_consignee`, `seller`, `forwarder`, `consignee`, `manufacturer`.
`arrival_port`	Locode	The UN/LOCODE for the port where the shipment will arrive in its final country, generally provided on an international shipment.
`arrival_port_actual`	DateTime	Actual date the shipment arrived at the final air or ocean port (not including final inland transportation)
`arrival_port_estimated`	DateTime	Estimated date the shipment will arrive at the final air or ocean port (not including final inland transportation)
`brand_code`	String	The code for the purchasing party’s brand.
`buyer_reference`	String	An additional reference used by the Buyer on the Purchase Order
`cargo_ready_date`	DateTime	Date the product is ready to be picked up from the supplier
`case_code`	String	The barcode displayed on the outer-most packaging of the product. Generally, this code is used to differentiate the case as a distinct retail product apart from the individual items inside the case.
`color_code`	String	A code representing the color of the product.
`color_description`	String	A human readable description of the color.
`confirmation_date`	DateTime	The date that the order was confirmed.
`containers`	Array<Container>	Array of containers
`costing_component`	Array<Costing Component>	Array of costing components
`country_of_origin`	String	The product's country of origin, as defined by the rules of origin. This may be different than the country from which the product is exported
`customer_product_id`	String	The product identifier (or style) of the product. Generally this is a higher level category which may have child variants specified by the SKU.
`customer_sku`	String	The customer’s stock keeping unit number. This represents the most detailed product. For example, this may be STYLE-COLOR-SIZE.
`delivery_mode`	String	The mode of delivery like `CY/CY`, `CFS/CY`, etc.
`departure_actual`	DateTime	Actual date and time the vessel departed from it's origin point
`departure_estimated`	DateTime	Estimated date and time the vessel will depart from 's origin point
`destination_warehouse`	String	The destination warehouse where the product is being sent
`ean_code`	String	The European Article Number code that is used to identify the product
`earliest_delivery_date`	DateTime	The earliest moment the supplier may deliver the product to the customer without penalty.
`earliest_in_dc_date`	DateTime	The earliest date which the shipment should be delivered.
`estimated_in_dc_date`	DateTime	The date the line is estimated to be in the distribution center.
`estimated_landed_cost`	Decimal	The alternate price or the estimated landed cost of this product
`ex_factory_date`	String	Date at which the supplier needs to ensure the shipment is ready to move out from the factory and handed over to the shipment forwarder
`extended_price`	Decimal	The total price for all items on the line.
`factory_country`	String	The country where the factory that made the product is located in
`fish_and_wildlife`	Boolean	Whether fish and wildlife customs clearance will be required for the goods
`goh`	String	The Garments on Hanger code for this product
`gross_weight_kgs`	Decimal	The gross weight of the item in Kilograms.
`gross_weight_measure_code`	String	The unit of measure for the gross weight
`gtin`	String	Global Trade Identification Number (https://www.barcode.graphics/education-gtin-14-barcode/)
`hot_flag`	Boolean	If true, then the line is considered important and should be tracked with additional care
`hts_code`	String	The product’s primary harmonized tariff code.
`inco_term`	String	The Incoterms under which the product will be purchased
`inco_term_named_place`	String	The place at which the Incoterms will be fulfilled. For example, the port for an FOB shipment.
`inner_pack_package_type_code`	String	The unit of measure for the inner pack.
`instructions`	String	Instructions from the customer to the supplier.
`invoice_number`	String	The invoice number
`item_height_cms`	Decimal	The height in centimeters of a single item or unit.
`item_length_cms`	Float	The length in centimeters of a single item or unit.
`item_length_cms`	Float	The length in centimeters of a single item or unit.
`item_material_description`	String	Description or breakdown of the item's materials or composition (ex. 75% polyester, 25% cotton).
`item_width_cms`	Decimal	The length in centimeters of a single item or unit.
`item_width_cms`	Decimal	The width in centimeters of a single item or unit.
`lading_port`	Locode	The UN/LOCODE for the lading port, generally provided on an international shipment.
`latest_delivery_date`	DateTime	The last moment the supplier may deliver the product to the customer without penalty.
`latest_in_dc_date`	DateTime	The latest date which the shipment should be delivered
`line_id`	String	The line number.
`marks_and_numbers`	String	The marks and numbers printed on the packaging.
`mode`	String	The mode of transport that should be used to deliver the product to the customer. Depending on the INCOTerm used, this may be the responsibility of the seller or the customer.
`native_reference_numbers`	Array<Native Reference Numbers>	Array of native reference numbers
`outer_pack_package_height_cms`	Float	The height of the outer pack in centimeters.
`outer_pack_package_length_cms`	Float	The length of the outer pack in centimeters.
`outer_pack_package_type_code`	String	The code that represents the type of packaging for the largest packaging group. We recommend that you use standardized package type codes.
`outer_pack_package_width_cms`	Float	The width of the outer pack in centimeters.
`package_height_cms`	Float	The height in centimeters of a single product pack unit.
`package_length_cms`	Float	The length in centimeters of a single product pack unit.
`package_width_cms`	Float	The width in centimeters of a single product pack unit.
`packaging_description`	String	Description of the packaging used, eg. “Brown Box”
`packaging_requirements`	String	Specific packaging requirements or packing instructions for the order line.
`prepack_type`	String	Instructions on the child product that make up this SKU if it is a prepack of multiple individual items
`price_ticket_instructions`	String	The instructions for the product tickets to detail whether or not the products will be ticketed and when in the process. For example: no tickets, supplier tickets, checkpoint tickets, cargo tickets
`price_ticket_type`	String	The type of ticket of the product. For example: whether it is stick on or hang tag
`product_category_code`	String	A general category code that covers multiple unique products, see `product_category_description` for examples
`product_category_description`	String	A general category description like Shirts, Outerwear, Electronics that covers multiple unique products
`product_description`	String	The product's description.
`product_group_name`	String	The group this product is a part of
`product_name`	String	The common or marketing name of product.
`quantity_fulfilled`	Decimal	The total quantity that has been delivered from the supplier to the customer.
`quantity_requested`	Decimal	The total number of products requested by the supplier. In a simple order scenario, this is the line quantity.
`required_in_store_date`	DateTime	The date that the product is required to be in store.
`retail_price`	Decimal	The retail price of this product
`sales_order_line_id`	String	A value uniquely identifying the associated Sales Order line.
`sales_order_number`	String	A value uniquely identifying the Sales Order issued by the supplier.
`sales_order_quantity_requested`	Float	The total number of products agreed to on the associated Sales Order line.
`second_size_code`	String	The second size code of the product
`ship_method_code`	String	Code representing method of shipment to be used.
`ship_method_description`	String	Instructions on method of shipment to be used.
`ship_to_location_id`	String	The customer’s identifying code for the ship to address.
`size_code`	String	A code representing the size of the product.
`size_description`	String	A human readable description of the size.
`sku_description`	String	A description of the item being ordered.
`sub_brand_code`	String	The code for the purchasing party’s sub brand.
`supplier_product_id`	String	product_id assigned by the supplier.
`total_inner_packages`	Float	The total number of inner packages included in the item.
`total_packages`	Decimal	The total number of packages included in the item.
`total_pieces`	Decimal	The total number of individual pieces or eaches being shipped. If there are 5 cartons with 10 shirts in each carton this value should be 50 (5 x 10).
`transaction_purpose_code`	String	The purpose of the transaction. For example, the code could indicate that it is an original, a cancellation of a previously-submitted purchase order, or a duplicate of a previously-submitted purchase order.
`unit_of_measure`	String	A code representing the unit of measure of the item being ordered.
`unit_of_measure_description`	String	A human readable description of the unit of measure.
`unit_price`	Decimal	The price for a single unit of the product.
`units_per_pack`	Decimal	The number of inner units in each quantity ordered. For example, if ordering 10 6-packs of shirts, then quantity_requested = 10 and units_per_pack = 6 and the total number of physical shirts is 60.
`upc`	String	The UPC code of the product.
`vendor_color`	String	The vendor specified color of the product
`volume_cbms`	Decimal	The volume of the item in Cubic Meters.
`volume_per_unit_cbms`	Float	The volume in cubic meters of a single unit of the product.
`warehouse_pick_ticket`	String	Pick ticket number to be used in warehouse.
`weight_per_unit_kgs`	Float	The weight in kilograms of a single unit of the product.

Address top

Name	Data Type	Description
`address_1`	String	The first line of the address.
`address_2`	String	The second line of the address.
`address_type`	String	The type of address represented by this element. Specific types may be defined on a per specification basis
`city`	String	The city.
`contact_name`	String	The full name of the contact person.
`country`	String	The 2-Digit ISO 3166 Alpha-2 Country Code. Like 'US'
`country_name`	String	The full name of the country like “United States”
`email`	String	The contact email address
`name`	String	The name associated with the address.
`phone_number`	String	The contact phone number
`postal_code`	String	The postal or ZIP code.
`state`	String	The state, province, or administrative division code
`state_name`	String	The full name of the state, province, or administrative division.
`unlocode`	String	The UN/LOCODE associated with the address. Like 'USCHI'

Costing Component top

Name	Data Type	Description	Required
`cost`	Decimal	Cost of the costing component.
`costing_code`	String	Code for the costing component

Attachment top

Name	Data Type	Description
`content`	Base64	A Base64 encoded string of the file content
`created_at`	Date	The timestamp this document was attached.
`created_by`	User	The user account / party responsible for adding the attachment.
`file_name`	String	The name of the file
`file_type_code`	String	A short code representing the logical type of file. (You might use 'INV' for an invoice.)
`file_type_description`	String	A descriptive file type like 'Invoice to customer X'
`media_type`	String	The Media Type of the file (also known as MIME Type or Content-Type)
`memo`	String	Information regarding the contents of the file.
`private`	Boolean	If true, attachment is considered a private attachment.
`source_system_uid`	String	A unique identifying code from the system of record for this attachment.

Container top

Name	Data Type	Description	Required
`container_number`	String	Identifying container number (including SCAC prefix)
`seal_1`	String	Container seal one

Order Container top

Name	Data Type	Description
`container_number`	String	Identifying container number (including SCAC prefix)
`seal_1`	String	Container seal one
`size_code`	String	ISO 6346 container size code (like 20G0)
`type_code`	String	ISO 6346 container type code (like 20GP)

Planned Shipment Legs top

Name	Data Type	Description
`arrival_estimated`	DateTime	The timestamp of the estimated date/time when shipment is estimated to arrive at the arrival unlocode.
`leg_sequence_number`	Decimal	The order of this leg within the shipment.
`mode`	String	The mode of transportation for the shipment. Recommended values: AIR, SEA, TRUCK, CARRY, RAIL, PARCEL.
`vessel_name`	String	The name of the vessel, typically for ocean shipments.
`voyage_number`	String	The voyage or flight number.

Planned Shipment Custom Declaration top

Name	Data Type	Description	Required
`broker_reference`	String	The Broker's file number for the customs declaration.

Planned Shipments top

Name	Data Type	Description
`arrival_unlocode`	String	The UN/LOCODE for the port where the shipment will arrive in its final country, generally provided on an international shipment.
`arrival_unlocode_description`	String	The description of the UN/LOCODE for the port where the shipment will arrive in its final country, generally provided as the arrival city.
`bill_of_lading_origin_unlocode`	String	The UN/LOCODE for the origin location of the bill of lading.
`bill_of_lading_origin_unlocode_description`	String	The description of the UN/Locode for the origin location of the bill of lading.
`booking_reference`	String	The reference number assigned to the booking by the booking party
`customs_declaration`	Array<Planned Shipment Custom Declaration>	Array of planned shipments customs declaration
`forwarder_reference`	String	The forwarder's reference number for the shipment.
`house_bill`	String	The house Bill of Lading Number.
`legs`	Array<Planned Shipment Legs>	Array of planned shipments legs
`master_bill`	String	The master Bill of Lading Number.
`service_level`	String	The level of service provided by the shipment's mode of transportation.

Milestones top

Name	Data Type	Description
`estimated_date`	DateTime	The timestamp of when the event is estimated to occur. (May be in the past or future)
`event_code`	String	A code that indicates the type of event. Each tracking provider uses their own list of codes which you can map to actions. In an EDI 315 this would generally map to the B403 segment.
`event_date`	DateTime	The time zone of the event date before converted to a timestamp.
`event_name`	String	The description of the type of event. Use the same event name for all events with the same event code.

Order Native Reference Numbers top

Name	Data Type	Description
`code`	String	A code identifying the type of reference number (ex. EDIREF, PO2).
`description`	String	A plain-text description of the reference number code. (ex. "EDI Reference Number", "Secondard PO Number").
`value`	String	The reference number value

Notes top

Name	Data Type	Description
`body`	String	A code that indicates the type of event. Each tracking provider uses their own list of codes which you can map to actions. In an EDI 315 this would generally map to the B403 segment.
`context`	String	The description of the type of event. Use the same event name for all events with the same event code.
`type`	String	The time zone of the event date before converted to a timestamp.

Native Reference Numbers top

Name	Data Type	Description
`code`	String	A code identifying the type of reference number (ex. EDIREF, PO2).
`description`	String	A plain-text description of the reference number code. (ex. "EDI Reference Number", "Secondard PO Number").
`value`	String	The reference number value

Standard Specifications

Purchase Order - JSON Specifiction

Summary

Objects

Root top

Order top

OrderLine top

Address top

Costing Component top

Attachment top

Container top

Order Container top

Planned Shipment Legs top

Planned Shipment Custom Declaration top

Planned Shipments top

Milestones top

Order Native Reference Numbers top

Notes top

Native Reference Numbers top

Example

Standard Specifications

Purchase Order - JSON Specifiction

Summary

Objects

Example

View as Plain TextCopy