Documentation

Object Reference

Addon

Describes an additional service provided by shipping method.

code
string

External code, as defined in carrier's system.

data
hash

Additional data that has to be passed to use the addon.

description
string

Description of the addon.

name
string

Internal identifier of an addon.

AddParcelRequest

shipment_id
string

site_id
string

AddParcelResponse

shipment

Address

Common address entity that used almost everywhere in Ingrid's API.

address_lines
string[]

List of address lines part of address such as street and building number

apartment_number
string

Number of the apartment.

attn
string optional

Attention field. Can be used to indicate an employee if the address is a company address

care_of
string optional

Care of part of address usually written as `c/o`

city
string

Name of the city

coordinates

Geolocation coordinates of the address. If reverse geolocation lookup of the address was successful this property will be populated. If coordinates are available they will be used to in service point search. In case of `search_address` coordinates can also be set by merchant if known.

country
string

Country should be specified as two uppercase letters (ISO Alpha-2). Example `SE` for Sweden, `ES` for Spain.

door_code
string optional

The door code to the main entrance of the building if applicable

name
string

Customer or company name

postal_code
string

Postal code (or zipcode in US)

region
string optional

Region can be a state or a province

street
string

Name of the street.

street_number
string

Number of the street.

Any

type_url
string

value
string

BookingMethod

carrier
string

custom
boolean

delivery_types

- UNKNOWN: Delivery type is not known for some reason. DELIVERY: Home delivery. PICKUP: Delivery to a service point or a locker. MAILBOX: Delivery to customer's mailbox. INSTORE: Delivery to one of the merchants stores. INWAREHOUSE: Delivery to the warehouse. This type is used with chain delivery in warehouse-warehouse-delivery/pickup.

id
string

name
string

parcel_type

- NONE: None indicates that parcels are not available for shipping method. Can be UNKNOWN, DELIVERY, PICKUP, MAILBOX, INSTORE, INWAREHOUSE

BookParcelsBulkRequest

shipment_ids
string[]

The IDs of the shipments which parcels should be booked.

BookParcelsBulkResponse

failed_shipment_ids
string[]

The IDs of the shipments which parcels failed to book.

succeeded_shipment_ids
string[]

The IDs of the shipments which parcels successfully booked.

BookParcelsRequest

Perform a booking request to generate tracking numbers, shipping labels and tracking links.

shipment_id
string required

The ID of the shipment which parcels should be booked.

BookParcelsResponse

Returns latest shipment state together with generated shipping labels, tracking numbers and tracking links.

shipment

Current shipment object state

BookPickupRequest

Book a pickup with the shipping company.

tracking_number
string required

Tracking number of the delivery which should be booked.

BookPickupResponse

Returns the state of the booked delivery.

delivery

Booked delivery state

CancelDeliveryRequest

Request to cancel a delivery if the shipment has not been picked up yet.

id
string

Delivery ID

tracking_number
string

Delivery tracking number

CancelShipmentRequest

Request to cancel a shipment if the shipment has not been picked up yet.

shipment_id
string

Shipment ID

Contents

Contents contains all goods sent in a Shipment or Parcel. Goods can either be defined directly by providing the full details of the goods, it can be referenced by transport order id or an external reference to goods defined by an external system.

external_orders

External orders contained in this shipment.

goods

Goods a.k.a. line items.

transport_orders

Transport orders contained in this shipment, so called consolidated shipment.

Coordinates

Geolocation coordinates

lat
number

Latitude

lng
number

Longitude

CreateCompositeShipmentFromOrderRequest

Request object that is used to create a Shipment from order.

addons

List of addons.

address_return
Address optional

Address where deliveries of this shipment should be returned to. A default return address is taken from the sender address ("address_from") which is usually the address of the warehouse.

contents

Contents of the shipment

courier_instructions
string

Optional instructions to the courier.

customs_declaration

Must be fully specified in case customs declaration should be generated for shipment.

delivery_time

Time range when the deliveries will most likely be delivered to the customer.

external_id
string

Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.

meta
hash

Generic key-value object that can be used to attach additional information to the shipment.

number_of_parcels
string

Number of parcels to generate. If supplied it will override the number of parcels created for this shipment. Otherwise the number of parcels will default to one

parcel_free_text
string

ParcelFreeText is a custom description to be assigned to all parcels in the shipment.

shipping_date
string required

The date that the shipment will most likely be dispatched from the warehouse.

shipping_method
string

Specific shipping product ID by which the generated parcels should be delivered. If tos_id is provided and the referenced order has field metadata.session.method, this field is optional. Otherwise, it is required.

tos_id
string required

TosId is an order ID as given from TOS.

CreateCompositeShipmentFromRequest

Request object that is used to create a Shipment from another source, for example via a COS session.

address_return
Address optional

Address where deliveries of this shipment should be returned to. A default return address is taken from the sender address ("address_from") which is usually the address of the warehouse.

cos_session_id
string required

CosSessionId a session id as given from COS.

customs_declaration

Must be fully specified in case customs declaration should be generated for shipment.

number_of_parcels
string

Number of parcels to generate. If supplied it will override the number of parcels created for this shipment. Otherwise the number of parcels will default to one.

parcel_free_text
string

ParcelFreeText is a custom description to be assigned to all parcels in the shipment.

parcels

If the parcels element is provided the number_of_parcels field should be set to the length of the parcels array or when number_of_parcel value is skipped the number_of_parcel will be calculated based on parcels array length.

shipping_date
string required

The date that the shipment will most likely be dispatched from the warehouse.

CreateCompositeShipmentRequest

Request object that is used to create a Shipment together with Parcels and Deliveries all at once.

addons

Addons that should be used for the shipment.

address_from
Address required

Address where the shipment will be dispatched from. Most often the address of the warehouse.

address_from_location_ref
string

ID of the warehouse, from which package will be delivered.

address_return
Address optional

Address where deliveries of this shipment should be returned to. A default return address is taken from the sender address ("address_from") which is usually the address of the warehouse.

address_to
Address required

Destination address. For example address of the service point or the click and collect store.

contents

Contents of shipment. Can be of different types - goods, transport orders and external orders.

courier_instructions
string

Optional instructions to the courier

customer_info

Contains the customer information such as name, email, phone and address. This field can be omitted, only if tos_id is not empty and the referenced order has enough data to derive customer info from it.

customs_declaration

Must be fully specified in case customs declaration should be generated for shipment.

delivery_time

Time range when the deliveries will most likely be delivered to the customer.

dimensions

Dimensions will override the dimensions for each created parcel. If not set, the total weight of each parcel will be calculated from the line items if that information is available. Default unit is millimeters. (mm)

direction_type
DirectionType optional

DirectionType informs about initial shipment direction.

external_id
string

Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.

line_items
LineItem[] deprecated

Use `contents` instead

location_ref
string

ID of the pickup location where the parcels should be delivered to.

meta
hash

Generic key-value object that can be used to attach additional information to the shipment.

number_of_parcels
string

Number of parcels to generate. If supplied it will override the number of parcels created for this shipment. Otherwise the number of parcels will default to one

outbound_shipment_id
string optional

ID of the OUTBOUND shipment (delivered from merchant to customer). Must be used only for the return shipment creation (with direction_type = "RETURN").

parcel_free_text
string

Custom description (notes) that will be assigned to all parcels in the shipment.

parcels

If the parcels element is provided the number_of_parcels field should be set to the length of the parcels array or when number_of_parcel value is skipped the number_of_parcel will be calculated based on parcels array length.

shipment_value
string

Total value of the shipment including tax. Example 10000 is 100 SEK.

shipping_category_ref
string

ID of shipping category that user choice belongs to. It's used to resolve virtual methods connected with ship. category.

shipping_date
string required

The date that the shipment will most likely be dispatched from the warehouse.

shipping_method
string required

Specific shipping product ID by which the generated parcels should be delivered.

tos_id
string optional

Order ID from TOS. If provided, you don't have to provide all the shipment details, Ingrid will take all the required data for the shipment from the order. But you still will have a possibility to override order data with the data you would give in the request.

weight
string

Weight in grams (g). If not set, the total weight of each parcel will be calculated from its line items if that information is available.

CreateCompositeShipmentResponse

Response from the shipment create call. Contains the latest shipment state.

shipment

Current shipment object state

CustomerInfo

Contains the necessary information about a customer in order to make a delivery

address

Customer's home address.

email
string

Customer's email.

phone
string

Customer's mobile phone number.

Customs

declaration

Customs declaration provided in request.

document

Customs declaration document available after booking the parcel with customs declaration request.

CustomsDeclaration

cn22

cn23

cp72

electronic_invoice_fedex

electronic_invoice_lotte

electronic_invoice_ups

general_customs_declaration

CustomsDeclarationDocument

format
string

File format (ex. "pdf", "png").

type

url
string

The url where the declaration label is located.

DateTimeRange

Provides a date interval. Depending on a case, `start` and `end` parts are not guaranteed to be present.

end
string

End of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`.

start
string

Start of the interval. Date is returned in RFC3339 format. Example `2018-09-08T22:47:31Z`

DeclarationCN

contents_explanation
string

Contents explanation - short general description.

contents_type

Content type of goods inside the parcel. For example - Sale, Gift etc. See ContentsType reference for details

currency
string

Purchase currency.

eori_number
string

EORI number for imports/exports from UK

items

List of items packed inside parcel.

total_gross_weight
integer

Total gross weight is parcel weight in grams (including packaging).

DeclarationCNItem

country_of_origin
string

Country of origin - country were this item were produced.

description
string

General description of this item.

hs_tariff_number
string

Harmonized System tariff number.

quantity
integer

Quantity of this item.

total_net_weight
integer

Total net weight of the item in grams (for the whole quantity).

total_value
integer

Total value of this item (for the whole quantity). Only integer values are supported and because of that provided value should always be in smallest currency unit possible (fractional monetary unit) For example, 25.99 USD should be converted to 2599

Delivery

Delivery is the parcel with start and end destination. A delivery always has one parcel that it belongs to.

addons

Addons available for the shipment.

address_from

Origin address for this delivery.

address_return

The return address to which a delivery that is returned should be sent.

address_to

Destination address for this delivery.

courier_instructions
string

Optional instructions to the courier.

created_at
string

Timestamp when delivery was created.

delivery_status
string

State of the delivery. Possible values are 'created','booked','pickup'.

delivery_time

Time range when the deliveries will most likely be delivered to the customer.

external_ref
string

Additional reference set by carrier which can be used to identify and search delivery.

id
string

Unique id of the delivery (uuid).

label_url
string

URL of the delivery's shipping label.

location_ref
string

ID of the service point location if applicable.

parcel_id
string

ID of the parcel which the delivery belongs to.

requested_shipping_method
string

Name of a Custom Shipping method used during booking.

return_label_url
string

URL of the delivery's return label.

return_tracking_number
string

Tracking number for the return delivery.

shipment_tracking_number
string

Consolidated tracking number for all deliveries in a shipment.

shipping_method
string

Shipping product ID for the delivery.

tracking_number
string

Tracking number for the delivery.

tracking_url
string

Tracking URL for the upcoming delivery if available.

transit_time
TransitTime deprecated

Transit time .

updated_at
string

Timestamp when delivery was last updated.

weight
string

Weight of the delivery in grams.

Dimensions

Length, height and width

height
string

Height in millimeters. For example `50` is 0,05 m

length
string

Length in millimeters. For example `140` is 0,14 m

width
string

Width in millimeters. For example `20` is 2 cm

ElectronicInvoiceFedex

contents_type

Content type of goods inside the parcel. For example - Sale, Gift etc. See ContentsType reference for details

currency
string

Purchase currency

items

List of items packed in the parcel

ElectronicInvoiceFedexItem

country_of_origin
string

Country where this item was produced

description
string

General description of this item

hs_tariff_number
string

Harmonized System tariff number

quantity
integer

Quantity of this item

quantity_units
string

Quantity units of this item

total_net_weight
integer

Total net weight of this item in grams (for the whole quantity)

total_value
integer

Total value of this item (for the whole quantity) Only integer values are supported and because of that provided value should always be in smallest currency unit possible (fractional monetary unit) For example, 25.99 USD should be converted to 2599

unit_value
integer

Value per unit of quantity Only integer values are supported and because of that provided value should always be in smallest currency unit possible (fractional monetary unit) For example, 25.99 USD should be converted to 2599

ElectronicInvoiceLotte

buyer_personal_customs_clearance_number
string

Buyer's personal customs clearance number/id.

currency
string

Purchase currency.

invoice_date
string

Date when the invoice was issued

invoice_number
string

Unique number that identifies the invoice

items

List of items packed inside parcel.

seller_customs_authorization_number
string

Seller's Customs Authorization Number. Required for orders above 6000 EUR.

sold_to

SoldTo is the address of the person who paid for the purchase.

ElectronicInvoiceLotteItem

brand
string

Brand of the item

country_of_origin
string

Country of origin - country were this item were produced.

description
string

General description of this item.

hs_tariff_number
string

Harmonized System tariff number.

quantity
integer

Quantity of this item.

total_value
integer

Total value of this item (for the whole quantity). Only integer values are supported and because of that provided value should always be in smallest currency unit possible (fractional monetary unit) For example, 25.99 USD should be converted to 2599

ElectronicInvoiceUPS

contents_explanation
string

Contents explanation - short general description.

contents_type

Content type of goods inside the parcel. For example - Sale, Gift etc. See ContentsType reference for details

currency
string

Purchase currency.

invoice_date
string

Date when the invoice was issued

invoice_number
string

Unique number that identifies the invoice

items

List of items packed inside parcel.

sold_to

SoldTo is the address of the person who paid for the purchase.

total_gross_weight
integer

Total gross weight is parcel weight in grams (including packaging).

ElectronicInvoiceUPSItem

country_of_origin
string

Country of origin - country were this item were produced.

description
string

General description of this item.

hs_tariff_number
string

Harmonized System tariff number.

quantity
integer

Quantity of this item.

total_value
integer

Total value of this item (for the whole quantity). Only integer values are supported and because of that provided value should always be in smallest currency unit possible (fractional monetary unit) For example, 25.99 USD should be converted to 2599

Error

code
integer

details

error
string

message
string

ExternalOrderContentItem

Reference to goods defined by an external system.

external_id
string

A reference to an external (merchant) order.

GeneralCustomsDeclaration

buyer_tax_id_number
string

For example EORI, VOEC, IOSS, HMRC.

contents_explanation
string

Contents explanation - short general description.

contents_type

Content type of goods inside the parcel. For example - Sale, Gift etc. See ContentsType reference for details.

currency
string

Purchase currency.

incoterms

International Commercial Terms.

invoice_date
string

Date when the invoice was issued.

invoice_number
string

Unique number that identifies the invoice.

items

List of items packed inside the parcel.

seller_tax_id_number
string

For example EORI, VOEC, IOSS, HMRC.

sold_to

The address of the person who paid for the purchase.

total_gross_weight
integer

Total gross weight of the parcel in grams (including packaging).

GeneralCustomsDeclarationItem

brand
string

Item's brand.

category
string

Item's commodity category, for example, babies products.

country_of_origin
string

Country of origin - country were this item were produced.

hs_tariff_number
string

Harmonized System tariff number.

name
string

Name of this item.

quantity
integer

Quantity of this item.

sku
string

SKU of this item.

unit_gross_weight
integer

Gross weight of the item in grams (including packaging), without taking quantity into account.

unit_net_weight
integer

Net weight of the item in grams, without taking quantity into account.

unit_value
integer

Value of the single item, without taking quantity into account. Only integer values are supported and because of that provided value should always be in smallest currency unit possible (fractional monetary unit). For example, 25.99 USD should be converted to 2599.

GetDeliveryResponse

Returns a delivery object

delivery

Delivery object state

GetShipmentResponse

Returns latest shipment state.

shipment

Current shipment object state

LineItem

Physical item of the parcel. A parcel can contain many line items. The parameters on the line item are used by the shipping rules framework to make better shipping decisions.

currency
string optional

Currency of the line item.

description
string optional

Description of the product

dimensions
Dimensions optional

Dimensions of the line item.

hs_tariff_number
string

Harmonized System tariff number.

name
string required

Product name or title

price
string optional

Price of the line item.

quantity
string required

Number of items.

sku
string required

Unique product identifier.

tags
string[]

List of tags or attributes that can be attached to this line item.

weight
string

Weight of the line item in grams. For example `200` is 0,2 kg.

ListConfiguredBookingMethodsResponse

methods

Parcel

Parcel is the physical package. One parcel can have at least one delivery at a time.

contents

Contents of the parcel.

created_at
string

Timestamp when parcel was created.

deliveries

Deliveries associated with the parcel.

dimensions
Dimensions optional

Length, height and width .

free_text
string

Custom description (notes) of a parcel.

id
string

Unique ID of the parcel (uuid).

label_free_text
string

Custom information about parcel visible on a label.

line_items
LineItem[] deprecated

Use `contents` instead

parcel_number
integer deprecated

Index number of the individual parcel in a shipment, i.e parcel 3 of 5 .

parcel_total
integer deprecated

Not used .

shipment_id
string

ID of the shipment that parcel belongs to (uuid).

updated_at
string

Timestamp when parcel was last updated.

weight
string

Total weight of the parcel in grams.

ParcelDetails

ParcelDetails contains additional information about parcels.

label_free_text
string

SendFreightDocumentsForReturnShipmentRequest

email
string

return_shipment_id
string

site_id
string

Shipment

Shipment is the top level object in SOM. A shipment can be composed of multiple parcels and each parcel can contain many deliveries. Only one delivery can be active at a time.

addons

Addons that should be used for the shipment.

address_from
Address required

Address where the shipment will be dispatched from. Most often the address of the warehouse .

address_return

Address where deliveries of this shipment should be returned to.

address_to
Address required

Destination address. For example address of the service point or the click and collect store .

contents

Contents of shipment. Can be of different types - goods, transport orders and external orders.

created_at
string

Timestamp when shipment was created.

customer_info
CustomerInfo required

Contains the customer information such as name, email, phone and address .

customs

Holds information about customs for the shipment.

direction_type

DirectionType informs about initial shipment direction.

external_id
string

Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.

id
string

ID of the shipment (uuid).

line_items
LineItem[] deprecated

Use `contents` instead

meta
hash

Generic key-value object that can be used to attach additional information to the shipment.

parcels

Parcels associated with this shipment.

shipment_value
string

Total value of the shipment including tax in cents. Example 10000 is 100 SEK.

shipping_date
string required

The date that the shipment will most likely be dispatched from the warehouse .

site_id
string

Site ID to which the shipment belongs to .

tos_id
string

ID of a corresponding order.

updated_at
string

Timestamp when shipment was last updated.

TransportOrderContentItem

Reference to goods defined by a transport order.

external_ref
string

Additional reference which can be used freely by the client to tie together a SOM shipment with an internal ID.

tos_id
string

Transport order id.

UpdateShipmentRequest

Update a shipment request

addons

List of shipment addons.

address_from
Address required

Address where the shipment will be dispatched from. Most often the address of the warehouse.

address_return
Address optional

Address where deliveries of this shipment should be returned to.

address_to
Address required

Destination address. For example address of the service point or the click and collect store.

courier_instructions
string

Optional instructions to the courier

customer_info

Contains the customer information such as name, email, phone and address.

delivery_time

Time range when the deliveries will most likely be delivered to the customer.

external_id
string

Can be used to store a unique identifier from the merchant. For example external order ID or external shipment ID.

location_ref
string

ID of the pickup location where the parcels should be delivered to.

meta
hash

Generic key-value object that can be used to attach additional information to the shipment.

parcel_free_text
string

Custom description (notes) that will be assigned to all parcels in the shipment.

shipment_id
string

Shipment ID

shipment_value
string

Total value of the shipment including tax. Example 10000 is 100 SEK.

shipping_date
string required

The date that the shipment will most likely be dispatched from the warehouse.

shipping_method
string required

Specific shipping product ID by which the generated parcels should be delivered.

weight
string deprecated

Weight in grams (g). If not set, the total weight of each parcel will be calculated from its line items if that information is available.

UpdateShipmentResponse

Returns the updated shipment

shipment

The updated shipment state

UpsertCustomsDeclarationRequest

customs_declaration

Customs declaration information that will be upserted to the shipment. If empty field given, information about the customs declaration will be removed from the shipment.

shipment_id
string

The ID of the shipment for which customs declaration upserting.

site_id
string

The ID of the site to which this request belongs.

UpsertCustomsDeclarationResponse

shipment

Last updated: Thu, Dec 08, 06:15 AM