Info
  • Web service URL: BASE_URL/api/Order


TABLE OF CONTENTS

1. Create a new order (POST)

Request Body (JSON) :

NameTypeRequired for PickupRequired for ShipmentDescription
ServiceIdintegerYesYesSee Service table
CourierIdinteger

Force sending to the specified courier. Bypasses all rules that limit couriers but applies rules that make changes to order. See Courier table.
CourierShipmentId
string

mandatory for ImportExternalOrder
CourierDispatchId
string

optional for ImportExternalOrder
ShipmentDateDateTimeYesYesShipment date
ShipmentDateEndDateTimeYes
Used for pick-up from third party (pick-up will be requested from ShipmentDate to ShipmentDateEnd)
AddressFromAddress[]Yes
See object below
AddressToAddress[]
YesSee object below
AddressReturnAddress[]


See object below - used only if return adress is different (used for specific carriers)
PaymentstringYesYesSender / Recipient  or  [int] 1 / 2
ContentContent[]YesYesSee object below
ExtraExtra[]

See object below
ExternalClientLocationstringYesYesWarehouse ID who triggers this order. It is configured in Locations in Innoship portal for each customer location.
ExternalOrderIdstring[100]
Only for EmagMarketplaceOrder ID from client system / For Emag orders this field is mandatory and should be populate with Emag OrderId
metadatastring[100]


Parameter that can be used for rules
SourceChannelstring[50]

Order channel
Observationstring[500]

Observations for label
ParametersParameters[]

See object below
CustomAttributesDictionary

This field can be used for any custom order attributes you may require. These attributes can be used in rules mechanism. An sample request can be seen in example page.


Address[] :

NameTypeRequired for Home DeliveryRequired for Lockers, PUDODescription
Namestring[64]YesYes
ContactPersonstring[100]YesYes
Countrystring[2]Yes

CountyNamestringYes!
not mandatory if PostalCode is sent
LocalityNamestringYes
either LocalityName + CountyName or LocalityName + PostalCode
AddressTextstring[100]Yes

StreetType
string


street type
StreetName
string


street name
streetNumber
string


street number
PostalCodestring[50]


Phonestring[64]YesYes
Emailstring[100]


FixedLocationIdstring
YesInnoship Fixed Location Id obtained using Get Fixed Locations Request (Location service)
CourierFixedLocationIdstring
Instead of FixedLocationIdCan be used instead of FixedLocationId if available. To use this field the CourierId is mandatory and the courierFixedLocationId is not validated by our system. Must be used for Emag orders with Locker delivery.


Content[] :

NameTypeRequiredDescription
EnvelopeCountintegerYesCount of unit of transport
ParcelsCountintegerYesCount of unit of transport
PalettesCountintegerYesCount of unit of transport
TotalWeightDecimalYesTotal weight for shipment
Contentsstring[100]YesDescription of shipment contents
Packagestring[100]
How is the shipment packed
OversizedPackageboolean
If shipment is over-sized set this to true
ParcelsParcel[]
Optional. Size and weight for each individual unit of transport
InvoiceNumber
string[32]
Yes - for commercial shipment for non - EU
InvoiceDate
Date
Yes - for commercial shipment for non - EU
InvoiceValue
Decimal
Yes - for commercial shipment for non - EU
InvoiceValueCurrency
string[3]
Yes - for commercial shipment for non - EU
ArticlesArticle[]Only for Non-EU shipments with customs declaration.
Optional. List of articles for customs declaration


Parcel[] :

NameTypeRequiredDescription
SequenceNointegerYes
SizeSize[]Yes
WeightDecimalYesvalue in kilograms
TypestringYesEnvelope (1), Parcel (2), Pallet (3)
Reference1string[100]YesContent for parcel
Reference2string[100]
NoReference free text
CustomerBarcodestring
Used if customer has internal barcodes on boxes, will be returned in AWB response so you can match each box with specific child AWB number from Courier
DangerousGood
DangerousGood[]
NoUsed if parcel contains dangerous goods items


Size[] :

NameTypeRequiredDescription
WidthDoubleYesvalue in centimeters
LengthDoubleYesvalue in centimeters
HeightDoubleYesvalue in centimeters


DangerousGood[] :

NameTypeRequiredDescription
ProductIdstringYesUN standard product id (eg: UN3480)
ProductDescriptionstringYesproduct description (eg: Lithium ion batteries)
ProductClassInt
Yesproduct class
QuantityClassification
string
Yes
Limited qty (LQ), Fully Regulated (FR) etc.
PackagingGroupType
string
Yes
eg: III
PackagingInstructions
string
Yes
eg: P965, 965IB
ChemicalRecordIdentifier
string
No
identifier


Article[] :

Name
Type
Required
Description
Quantity
integer
Yes
Number of items
Description
string[50]
YesDescription of the article
CountryOfOriginstring[3]
Only for Non-EU shipments with customs declaration.
Country of origin of the article (complies with ISO 3166-1 alfa-2)
Tariff
string[18]
Only for Non-EU shipments with customs declaration.
Tariff code
WeightNetDecimalOnly for Non-EU shipments with customs declaration.
Net weight of articles (kg)
WeightGross
DecimalOnly for Non-EU shipments with customs declaration.
Gross weight of articles (kg)
PricePerPieceAmount
DecimalOnly for Non-EU shipments with customs declaration.
Price/Value of the single article
PricePerPieceAmountCurrencyString[3]Only for Non-EU shipments with customs declaration.
Currency code
skuString[]

Stock keeping unit


Extra[] :

NameTypeRequiredDescription
BankRepaymentAmountDecimal
Amount of money for cash on delivery - will be returned via bank
BankRepaymentCurrencystring[3]
Currency for bank repayment amount.
Bankstring[50]
Bank name - Required for pick-ups with Bank Repayment Amount.
BankIBANstring[35]
Sender IBAN code - Required for pick-ups with Bank Repayment Amount.
BankAccountHolderstring[]

Sender Bank Account holder
CashOnDeliveryAmountDecimal
Amount of money for cash on delivery - will be returned as cash
cashOnDeliveryAmountCurrencystring[3]
Currency for cash on delivery amount.
CashOnDeliveryPayoutToLocation 
boolean
Third party COD (used for specific carriers)
DeclaredValueAmountDecimal
Declared shipment valued for customs declaration
DeclaredValueAmountCurrencystring[3]
Currency for declared value amount
OpenPackageboolean
Open package request
SaturdayDeliveryboolean
Deliver on Saturday
InsuranceAmountDecimal
Amount to be insured
insuranceAmountCurrency
string[3]

Currency for insurance amount
Reference1string[100]
Reference free text 1 - Can be mapped to courier fields
Reference2string[100]
Reference free text 2 - Can be mapped to courier fields
Reference3string[100]
Reference free text 3 - Can be mapped to courier fields
Reference4string[100]
Reference free text 4 - Can be mapped to courier fields
ReturnOfDocumentsboolean
Return of Documents (ROD) additional service requires documents to be returned upon the delivery of the primary shipment.
ReturnOfDocumentsCommentstring[250]
Comment for returned documents
ReturnPackageboolean
additional service - return package (swap)
ReturnVoucherboolean
additional service - creates a voucher label
CustomsDeclarationCustomsDeclaration[]Only for Non-EU shipments with customs declaration.

Custom declaration forms
UitCode
string[16]

used for Palet High Risk Goods
Incotermstring[3]
used for specific carriers for EU shipments


CustomDeclaration[] :

Name
Type
Required
Description
ExporterAddress[]
Yes

ImporterAddress[]
Yes

ExporterTaxIdstring[16]
optional/required depending on the country of the recipient/importer Sender/exporter tax identification number (Tax ID)
ExporterEoristring[32]
optional/required depending on the country of the recipient/importer Sender/exporter Economic Operator Registration and Identification number (EORI)
ExporterUkimsNumber
string[32]
optional/required depending on the country of the recipient/importer 
Sender/exporter UK Internal Market Scheme
ExporterBNstring[32]optional/required depending on the country of the recipient/importer
BN number
ImporterTaxIdstring[16]optional/required depending on the country of the recipient/importer 
Receiver/importer tax identification number (Tax ID) 
ImporterEoristring[32]optional/required depending on the country of the recipient/importer 
Receiver/importer Economic Operator Registration and Identification number (EORI) 
ImporterUkimsNumber
string[32]
optional/required depending on the country of the recipient/importer
Importer /exporter UK Internal Market Scheme
Reasoninteger
Yes Reason for shipment (10 - commercial shipment, 12- non-commercial shipment)
Incotermstring[3]Yes
AttachmentsAttachments[]No


Attachments[] :

Name
Type RequiredDescription

Name
string[255]Yes
Name of file
ContentstringYesFile (binary content), coded MIME base64


Parameters[] :

NameTypeDescription
GetParcelsBarcodesbooleanWill reply with all Barcodes object for clients who print their own label
IncludeCourierResponsebooleanThis will include Carrier response in Innoship response object CourierResponse[]. The format is carrier specific.
IncludePriceBreakdownbooleanprice details for each price comp
OverwriteLocationAddressWithSenderDetails
booleanoverwrite sender details with AddressFrom 
ImportExternalOrder
booleanused to insert carrier external aw(courierShipmentId &  CourierId - mandatory)


Example Request:


{
  "serviceId": 1,
  "shipmentDate": "2020-02-16",
  "addressTo": {
    "name": "Name of recipient",
    "contactPerson": "Contact for recipient",
    "country": "RO",
    "countyName": "Bucuresti",
    "localityName": "Bucuresti",
    "addressText": "adress text 10",
    "postalCode": "123456",
    "phone": "+40734123456",
    "email": "[email protected]"
  },
  "payment": "sender",
  "content": {
    "envelopeCount": 0,
    "parcelsCount": 1,
    "palettesCount": 0,
    "totalWeight": 1,
    "contents": "t-shirt",
    "package": "box",
    "oversizedPackage": false,
    "parcels": [
      {
        "sequenceNo": 1,
        "size": {
          "width": 20,
          "height": 50,
          "length": 20
        },
        "weight": 1,
        "type": "parcel",
        "reference1": "invoice for order 222"
      }
    ]
  },
  "extra": {
    "bankRepaymentAmount": 50.25,
    "openPackage": true,
    "insuranceAmount": 100
  },
  "parameters": {
    "GetParcelsBarcodes": false
  },
  "externalClientLocation": "1",
  "externalOrderId": "212",
  "metadata": "extra data information",
  "sourceChannel": "ONLINE",
  "observation": "Call one hour before"
}


Example Request with Custom Attributes

{
  "serviceId": 1,
  "shipmentDate": "2020-02-16",
  "addressTo": {
    "name": "Name of recipient",
    "contactPerson": "Contact for recipient",
    "country": "RO",
    "countyName": "Bucuresti",
    "localityName": "Bucuresti",
    "addressText": "adress text 10",
    "postalCode": "123456",
    "phone": "+40734123456",
    "email": "[email protected]"
  },
  "payment": "sender",
  "content": {
    "envelopeCount": 0,
    "parcelsCount": 1,
    "palettesCount": 0,
    "totalWeight": 1,
    "contents": "t-shirt",
    "package": "box",
    "oversizedPackage": false,
    "parcels": [
      {
        "sequenceNo": 1,
        "size": {
          "width": 20,
          "height": 50,
          "length": 20,
        },
        "weight": 1,
        "type": "parcel",
        "reference1": "invoice for order 222"
      }
    ]
  },
   "CustomAttributes":{
      "ClientId":"907882",
      "LocationId":"3323",
      "CustomerGroup": "Silver"
   },
  "extra": {
    "bankRepaymentAmount": 50.25,
    "openPackage": true,
    "insuranceAmount": 100
  },
  "parameters": {
    "GetParcelsBarcodes": false
  },
  "externalClientLocation": "1",
  "externalOrderId": "212",
  "metadata": "extra data information",
  "sourceChannel": "ONLINE",
  "observation": "Call one hour before"
}

2. Create a new order - Response

NameTypeDescription
ClientOrderIdstringInnoship order ID.
CourierShipmentIdstringGenerated shipment AWB from courier(main).
CourierParcelsBarcodesBarcodes[]Optional based on parameter GetParcelsBarcodes from request. if parameter is set to false this object will not exist in response.
CourierResponseObject[]Optional based on parameter IncludeCourierResponse. If parameter is set to false this object will not exist in response. The format of this object is Carrier specific.
CourierintegerSee Courier Table
PriceShipmentPrice[]
ExtraExtra[]All extra services requested. The same object from request documentation This will also include any changes from Rules.
CalculatedDeliveryDateDate


Barcodes[] :

NameTypeDescription
sequenceNointegerConsecutive id for order parcels
BarcodestringAWB barcode for this parce
CustomerBarcodestringCustomer Barcode got in the request


ShipmentPrice[] :

NameTypeDescription
AmountDoubleTotal amount (before VAT) in customer’s currency.
VatDoubleVAT amount in customer’s currency.
TotalDoubleTotal amount (amount + vat) in customer’s currency.
CurrencystringCurrency code.


Example Response (Success - HTTP code 200):

{
  "ClientOrderId": "1|905230964",
  "CourierShipmentId": "905230964",
  "Courier": 1,
  "Price": {
    "Amount": 13.13,
    "VAT": 2.49,
    "TotalAmount": 15.62,
    "Currency": "RON"
  },
  "CalculatedDeliveryDate": "2020-07-27T00:00:00+00:00",
  "TrackPageUrl": "https://track.innoship.io/9c2bc826f5a54ffc8bee9296c53c9d1b",
  "Extra": {
    "BankRepaymentAmount": 32.12,
    "BankRepaymentCurrency": "RON",
    "OpenPackage": true
  }
}


Example Response (Success with Barcodes - HTTP code 200):

{
  "ClientOrderId": "1|905230966",
  "CourierShipmentId": "905230966",
  "Courier": 1,
  "CourierParcelsBarcodes": [
    {
      "SequenceNo": 1,
      "Barcode": "905230966"
    }
  ],
  "Price": {
    "Amount": 13.13,
    "VAT": 2.49,
    "TotalAmount": 15.62,
    "Currency": "RON"
  },
  "CalculatedDeliveryDate": "2020-07-27T00:00:00+00:00",
  "TrackPageUrl": "https://track.innoship.io/e40841d3f20849898dab6db12ba01cd4",
  "Extra": {
    "BankRepaymentAmount": 32.12,
    "BankRepaymentCurrency": "RON",
    "OpenPackage": true
  }
}

Example Response (Success with PriceBreakdown- HTTP code 200):

{
    "clientOrderId": "1|1001152135",
    "courierShipmentId": "1001152135",
    "courier": 1,
    "price": {
        "amount": 8.76,
        "vat": 1.66,
        "totalAmount": 10.42,
        "currency": "RON",
        "priceComponents": {
            "km": 0.0,
            "kmFixed": 0.0,
            "envelopes": 0.0,
            "contentWeight": 7.71,
            "cashOnDelivery": 0.0,
            "bankRepayment": 1.05000,
            "openPackage": 0.0,
            "saturdayDelivery": 0.0,
            "returns": 0.0,
            "priceForExtraParcel": 0.0,
            "pickupThirdParty": 0.0,
            "insurance": 0.0,
            "fuelSurcharge": 0.000
        }
    },
    "calculatedDeliveryDate": "2022-12-28T22:00:00Z",
    "trackPageUrl": "https://track.innoship.io/dLMib6fdrUaHLvXSdISG0g",
    "extra": {
        "bankRepaymentAmount": 100.0,
        "bankRepaymentCurrency": "RON",
        "openPackage": false,
        "saturdayDelivery": false,
        "reference2": "test",
        "reference3": "test1",
        "reference4": "1",
        "returnPackage": true
    }
}


Example Response (Success with CourierResponse- HTTP code 200):

  "ClientOrderId": "1|905230968",
  "CourierShipmentId": "905230968",
  "Courier": 1,
  "Price": {
    "Amount": 13.13,
    "VAT": 2.49,
    "TotalAmount": 15.62,
    "Currency": "RON"
  },
  "CalculatedDeliveryDate": "2020-07-27T00:00:00+00:00",
  "TrackPageUrl": "https://track.innoship.io/eb8602faccb445209e421b053b20bfe4",
  "CourierResponse": {
    "IdComanda": 218259769,
    "Sender": {
      "CityCenterName": "PITESTI",
      "CityCenterId": 0,
      "LocationId": 1005962049,
      "Name": "ECOM TEST",
      "CountyId": 0,
      "CountyName": "Arges",
      "LocalityId": 157,
      "LocalityName": "PITESTI",
      "StreetId": 0,
      "StreetName": "",
      "BuildingNumber": "",
      "AddressText": "",
      "ContactPerson": "",
      "PhoneNumber": " ",
      "Email": "",
      "CodPostal": null,
      "CountryId": null
    },
    "Recipient": {
      "CityCenterName": "BUCURESTI",
      "CityCenterId": 0,
      "LocationId": 1,
      "Name": "Name of recipient",
      "CountyId": 1,
      "CountyName": "Bucuresti",
      "LocalityId": 150,
      "LocalityName": "BUCURESTI",
      "StreetId": 0,
      "StreetName": "",
      "BuildingNumber": "",
      "AddressText": "adress text 10",
      "ContactPerson": "Contact for recipient",
      "PhoneNumber": "+40734123456",
      "Email": "[email protected]",
      "CodPostal": null,
      "CountryId": null
    },
    "SenderClientId": null,
    "TertiaryClientId": null,
    "TertiaryLocationId": null,
    "Parcels": 1,
    "Envelopes": 0,
    "TotalWeight": 1,
    "ServiceId": 1,
    "DeclaredValue": 0,
    "CashRepayment": 0,
    "BankRepayment": 32.12,
    "OtherRepayment": "",
    "BarCodeRepayment": null,
    "PaymentInstrumentId": 0,
    "PaymentInstrumentValue": 0,
    "HasTertReimbursement": false,
    "OpenPackage": false,
    "PriceTableId": 1,
    "ShipmentPayer": 1,
    "ShippingRepayment": null,
    "SaturdayDelivery": false,
    "MorningDelivery": false,
    "HasNonStandardParcel": false,
    "DeliveryTime": 0,
    "Observations": "Call one hour before",
    "PackageContent": "t-shirt",
    "CustomString": "",
    "BarCode": "905230968",
    "ParcelCodes": [
      {
        "Code": "905230968",
        "Type": 1,
        "Weight": 0,
        "Length": null,
        "Width": null,
        "Height": null
      }
    ],
    "ValidationDate": "2020-07-25T19:43:06.937",
    "ShippingCost": {
      "BaseCost": 0,
      "ExtraKmCost": 0,
      "WeightCost": 0,
      "InsuranceCost": 0,
      "SpecialCost": 0,
      "RepaymentCost": 0,
      "Subtotal": 27.35,
      "Tax": 6.57,
      "GrandTotal": 33.92
    },
    "Status": "Not printed",
    "SenderReference1": "",
    "RecipientReference1": "",
    "RecipientReference2": "",
    "InvoiceReference": "",
    "Length": null,
    "Width": null,
    "Height": null,
    "TransitPriority": "A",
    "TransitRoute": "Bucuresti",
    "TransitCodes": "077",
    "DeliveryRoute": "Bucuresti\r077 - 10-78-09"
  },
  "Extra": {
    "BankRepaymentAmount": 32.12,
    "BankRepaymentCurrency": "RON",
    "OpenPackage": true
  }
}


Example Response

NameTypeDescription
contextstringMessage context, if associated. This refers to an item that is wrong and should be corrected.
messagestringError message in language specified in the request.