Info- Web service URL: BASE_URL/api/Order
|
TABLE OF CONTENTS |
1. Create a new order (POST)
Request Body (JSON) :
Name | Type | Required for Pickup | Required for Shipment | Description |
ServiceId | integer | Yes | Yes | See Service table |
CourierId | integer |
|
| 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 |
ShipmentDate | DateTime | Yes | Yes | Shipment date |
ShipmentDateEnd | DateTime | Yes |
| Used for pick-up from third party (pick-up will be requested from ShipmentDate to ShipmentDateEnd) |
AddressFrom | Address[] | Yes |
| See object below |
AddressTo | Address[] |
| Yes | See object below |
AddressReturn | Address[]
|
|
| See object below - used only if return adress is different (used for specific carriers)
|
Payment | string | Yes | Yes | Sender / Recipient or [int] 1 / 2 |
Content | Content[] | Yes | Yes | See object below |
Extra | Extra[] |
|
| See object below |
ExternalClientLocation | string | Yes | Yes | Warehouse ID who triggers this order. It is configured in Locations in Innoship portal for each customer location. |
ExternalOrderId | string[100] |
| Only for EmagMarketplace | Order ID from client system / For Emag orders this field is mandatory and should be populate with Emag OrderId |
metadata | string[100]
|
|
| Parameter that can be used for rules
|
SourceChannel | string[50] |
|
| Order channel |
Observation | string[500] |
|
| Observations for label |
Parameters | Parameters[] |
|
| See object below |
CustomAttributes | Dictionary |
|
| 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[] :
Name | Type | Required for Home Delivery | Required for Lockers, PUDO | Description |
Name | string[64] | Yes | Yes |
|
ContactPerson | string[100] | Yes | Yes |
|
Country | string[2] | Yes |
|
|
CountyName | string | Yes! |
| not mandatory if PostalCode is sent |
LocalityName | string | Yes |
| either LocalityName + CountyName or LocalityName + PostalCode |
AddressText | string[100] | Yes |
|
|
StreetType
| string
|
|
| street type
|
StreetName
| string
|
|
| street name |
streetNumber
| string
|
|
| street number |
PostalCode | string[50] |
|
|
|
Phone | string[64] | Yes | Yes |
|
Email | string[100] |
|
|
|
FixedLocationId | string |
| Yes | Innoship Fixed Location Id obtained using Get Fixed Locations Request (Location service) |
CourierFixedLocationId | string |
| Instead of FixedLocationId | Can 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[] :
Name | Type | Required | Description |
EnvelopeCount | integer | Yes | Count of unit of transport |
ParcelsCount | integer | Yes | Count of unit of transport |
PalettesCount | integer | Yes | Count of unit of transport |
TotalWeight | Decimal | Yes | Total weight for shipment |
Contents | string[100] | Yes | Description of shipment contents |
Package | string[100] |
| How is the shipment packed |
OversizedPackage | boolean |
| If shipment is over-sized set this to true |
Parcels | Parcel[] |
| 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 |
|
Articles | Article[] | Only for Non-EU shipments with customs declaration.
| Optional. List of articles for customs declaration |
Parcel[] :
Name | Type | Required | Description |
SequenceNo | integer | Yes |
|
Size | Size[] | Yes |
|
Weight | Decimal | Yes | value in kilograms |
Type | string | Yes | Envelope (1), Parcel (2), Pallet (3) |
Reference1 | string[100] | Yes | Content for parcel |
Reference2 | string[100]
| No | Reference free text |
CustomerBarcode | string |
| 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[]
| No | Used if parcel contains dangerous goods items |
Size[] :
Name | Type | Required | Description |
Width | Double | Yes | value in centimeters |
Length | Double | Yes | value in centimeters |
Height | Double | Yes | value in centimeters |
DangerousGood[] :
Name | Type | Required | Description |
ProductId | string | Yes | UN standard product id (eg: UN3480) |
ProductDescription | string | Yes | product description (eg: Lithium ion batteries) |
ProductClass | Int
| Yes | product 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]
| Yes | Description of the article
|
CountryOfOrigin | string[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
|
WeightNet | Decimal | Only for Non-EU shipments with customs declaration.
| Net weight of articles (kg)
|
WeightGross
| Decimal | Only for Non-EU shipments with customs declaration.
| Gross weight of articles (kg)
|
PricePerPieceAmount
| Decimal | Only for Non-EU shipments with customs declaration.
| Price/Value of the single article
|
PricePerPieceAmountCurrency | String[3] | Only for Non-EU shipments with customs declaration.
| Currency code |
sku | String[]
|
| Stock keeping unit
|
Name | Type | Required | Description |
BankRepaymentAmount | Decimal |
| Amount of money for cash on delivery - will be returned via bank |
BankRepaymentCurrency | string[3] |
| Currency for bank repayment amount. |
Bank | string[50] |
| Bank name - Required for pick-ups with Bank Repayment Amount. |
BankIBAN | string[35] |
| Sender IBAN code - Required for pick-ups with Bank Repayment Amount. |
BankAccountHolder | string[]
|
| Sender Bank Account holder |
CashOnDeliveryAmount | Decimal |
| Amount of money for cash on delivery - will be returned as cash |
cashOnDeliveryAmountCurrency | string[3] |
| Currency for cash on delivery amount. |
CashOnDeliveryPayoutToLocation
| boolean |
| Third party COD (used for specific carriers)
|
DeclaredValueAmount | Decimal |
| Declared shipment valued for customs declaration |
DeclaredValueAmountCurrency | string[3] |
| Currency for declared value amount |
OpenPackage | boolean |
| Open package request |
SaturdayDelivery | boolean |
| Deliver on Saturday |
InsuranceAmount | Decimal |
| Amount to be insured |
insuranceAmountCurrency
| string[3]
|
| Currency for insurance amount |
Reference1 | string[100] |
| Reference free text 1 - Can be mapped to courier fields |
Reference2 | string[100] |
| Reference free text 2 - Can be mapped to courier fields |
Reference3 | string[100] |
| Reference free text 3 - Can be mapped to courier fields |
Reference4 | string[100] |
| Reference free text 4 - Can be mapped to courier fields |
ReturnOfDocuments | boolean |
| Return of Documents (ROD) additional service requires documents to be returned upon the delivery of the primary shipment. |
ReturnOfDocumentsComment | string[250] |
| Comment for returned documents |
ReturnPackage | boolean |
| additional service - return package (swap) |
ReturnVoucher | boolean |
| additional service - creates a voucher label |
CustomsDeclaration | CustomsDeclaration[] | Only for Non-EU shipments with customs declaration.
| Custom declaration forms |
UitCode
| string[16]
|
| used for Palet High Risk Goods |
Incoterm | string[3] |
| used for specific carriers for EU shipments
|
Name
| Type
| Required
| Description
|
---|
Exporter | Address[]
| Yes
|
|
Importer | Address[]
| Yes
|
|
ExporterTaxId | string[16]
| optional/required depending on the country of the recipient/importer | Sender/exporter tax identification number (Tax ID)
|
ExporterEori | string[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
|
ExporterBN | string[32] | optional/required depending on the country of the recipient/importer
| BN number
|
ImporterTaxId | string[16] | optional/required depending on the country of the recipient/importer
| Receiver/importer tax identification number (Tax ID)
|
ImporterEori | string[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
|
Reason | integer
| Yes | Reason for shipment (10 - commercial shipment, 12- non-commercial shipment)
|
Incoterm | string[3] | Yes |
|
Attachments | Attachments[] | No |
|
Attachments[] :
Name
| Type | Required | Description |
Name
| string[255] | Yes
| Name of file |
Content | string | Yes | File (binary content), coded MIME base64
|
Parameters[] :
Name | Type | Description |
GetParcelsBarcodes | boolean | Will reply with all Barcodes object for clients who print their own label |
IncludeCourierResponse | boolean | This will include Carrier response in Innoship response object CourierResponse[]. The format is carrier specific. |
IncludePriceBreakdown | boolean | price details for each price comp |
OverwriteLocationAddressWithSenderDetails
| boolean | overwrite sender details with AddressFrom
|
ImportExternalOrder
| boolean | used 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
Name | Type | Description |
ClientOrderId | string | Innoship order ID. |
CourierShipmentId | string | Generated shipment AWB from courier(main). |
CourierParcelsBarcodes | Barcodes[] | Optional based on parameter GetParcelsBarcodes from request. if parameter is set to false this object will not exist in response. |
CourierResponse | Object[] | 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. |
Courier | integer | See Courier Table |
Price | ShipmentPrice[] |
|
Extra | Extra[] | All extra services requested. The same object from request documentation This will also include any changes from Rules. |
CalculatedDeliveryDate | Date |
|
Name | Type | Description |
sequenceNo | integer | Consecutive id for order parcels |
Barcode | string | AWB barcode for this parce |
CustomerBarcode | string | Customer Barcode got in the request |
Name | Type | Description |
Amount | Double | Total amount (before VAT) in customer’s currency. |
Vat | Double | VAT amount in customer’s currency. |
Total | Double | Total amount (amount + vat) in customer’s currency. |
Currency | string | Currency 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
Name | Type | Description |
context | string | Message context, if associated. This refers to an item that is wrong and should be corrected. |
message | string | Error message in language specified in the request. |