Duty Refunds Landmark API (1.0.0)

Download OpenAPI specification:Download

Overview

The Duty Refunds Landmark API can be used to create Landmark and Amazon Shipping shipping labels for eCommerce parcels that are being shipped from Landmark's facility in Brussels to the United Kingdom. This ensures the created shipping labels are compliant and utilizes Duty Refunds' accounts for duty & VAT management. This API can also be used to track and cancel shipments, as well as to create return shipping labels.

Authentication

The API uses a Basic Auth scheme for secure access.
Authentication requires the Duty Refunds API key and secret for verification.

Rate Limits and Throttling

Application-level limit: 300 requests per 1 minute, per endpoint, per client API user

ℹ Note: For application-level limits, hits are counted per actual minute (i.e. from 10:02:01.00 to 10:03:00.99). So the counter is reset at the first second of each new minute.

Getting Access

Obtain a Duty Refunds API key by contacting your account manager or partnerships@dutyrefunds.co.uk

Shipment

Endpoints related to shipments

Create Shipment

This endpoint creates a shipment in Mercury and generates an Amazon Shipping label for the final mile delivery.

SecuritybasicAuth

Request

Request Body schema: application/json

Reference required	string Customer Reference, or Order Number. Primary shipment identifier.
required	object
OrderTotal	number Conditional. Amount paid by the customer for all the items in their order. Must be passed in instances where the shipment information represents a partial shipment of products comprising a larger order.
OrderInsuranceFreightTotal	number Conditional. Amount paid by the customer for shipping their entire order. Must be passed in instances where the shipment information represents a partial shipment of products comprising a larger order.
ShipmentInsuranceFreight required	number Amount charged for shipping and any insurance for the shipment. This value does not include the amount charged for purchased items (i.e. Item Unit Value).
ItemsCurrency	string Optional, and only used when client uses multiple currencies. If used, pass the 3 character ISO 4217 code to represent the currency (i.e. USD, CAD).
ProduceLabel	boolean Optional, Whether or not to return a generic label even though the shipment will not be processed.
LabelFormat	string Optional, only used if ProduceLabel = true. Default is PDF. Also supports JPG, GIF, BMP and PNG.
LabelEncoding	string Optional, only used if ProduceLabel = true. Default is "LINKS". LINKS - returns links to all labels which must be retrieved in tag. BASE64 - Base64 encoded label image is returned directly in the response in tag. BASE64COMPRESSED - GZcompressed and Base64 encoded label image is returned directly in the response in tag.
required	object Conditional. Required if providing third party logistics for the client. Information here represents the actual vendor (retailer) name and address for the items sold in the order.
RequiresVATRepresentation	boolean Default: true Optional, Whether or not to provide UK VAT representation for this package.
required	object Package details.
required	Array of objects Required for customs if the shipment will be crossing the border.
property name* additional property	string

Responses

200

Shipment Created Successfully

400

Error response

401

Unauthorized

429

Application-level throttling response

post/shipment

Request samples

Payload
curl
Node.js
Python

application/json

{"Reference": "3245325",
"ShipTo": {"Name": "Test Company",
"Attention": "Ole Olsen",
"Address1": "5130 Halford Drive",
"Address2": "Building #C",
"Address3": "Unit 1",
"City": "Windsor",
"State": "ON",
"PostalCode": "N9A6J3",
"Country": "CA",
"Phone": "1-519-737-9101",
"Email": "orders@test.com"
},
"OrderTotal": 187.98,
"OrderInsuranceFreightTotal": 20.65,
"ShipmentInsuranceFreight": 20.65,
"ItemsCurrency": "USD",
"ProduceLabel": false,
"LabelFormat": "PDF",
"LabelEncoding": "LINKS",
"VendorInformation": {"VendorName": "Test Company Legal Name",
"VendorPhone": "12223334444",
"VendorEmail": "contact@vendor.com",
"VendorAddress1": "Sample Company Street",
"VendorAddress2": "Suite 135",
"VendorCity": "Santa Barbara",
"VendorState": "CA",
"VendorPostalCode": "93101",
"VendorCountry": "US",
"VendorBusinessNumber": "12345",
"VendorRGRNumber": "123",
"VendorIOSSNumber": "IM1234567891",
"VendorEORINumber": "12345"
},
"Field1": "Any type of data",
"Field2": "Purchased with Credit Card",
"Field3": "99000029327172321",
"Field4": "123198012",
"Field5": "Stored information",
"Package": {"WeightUnit": "LB",
"Weight": 4.5,
"DimensionsUnit": "IN",
"Length": 12,
"Width": 12,
"Height": 12,
"PackageReference": "98233310"
},
"Items": [{"Sku": "7224059",
"Quantity": 2,
"UnitPrice": 93.99,
"Description": "Women's Shoes",
"HSCode": "640399.30.00",
"CountryOfOrigin": "CN",
"URL": "",
"ReturnCustomsInfo": {"HSCode": "6403993000",
"HSRegionCode": "US"
},
"DangerousGoodsInformation": {"ContainsDangerousGoods": true,
"UNCode": "UN3481",
"PackingGroup": "II",
"PackingInstructions": "PS967S1",
"ItemWeight": 10,
"ItemWeightUnit": "kg",
"ItemVolume": 30,
"ItemVolumeUnit": "ML"
}
}
]
}

Response samples

application/json

{"Test": "true",
"Result": {"Success": "true",
"ResultMessage": "Shipment 3245325 was successfully imported.",
"Packages": [{"LabelLink": "https://api.landmarkglobal.com/download/get-label.php?hid=5SalTlxR8JkpE%2FCW4HxGD0ghMOXXA%2F0rebjGm9EeaVlkG58%3D_5KAZZsOEn9E4p5Sy",
"LabelImages": [{"LabelImage": "23987B3KD0LK211AF......"
}
],
"TrackingNumber": "LTN329122N2",
"LandmarkTrackingNumber": "LTN329122N2",
"TrackingURL": "https://track.amazon.co.uk/tracking/A12414424593",
"LandmarkTrackingURL": "https://track.landmarkglobal.com/?sid=329122N2",
"PackageReference": "98233310",
"ImportDutyGBP": 10.23,
"VATGBP": 34.56,
"TotalDutyVATGBP": 44.79
}
]
}
}

Track a package

Track Shipment By Reference Or TrackingNumber Or PackageReference. This endpoint can also be used to track a return shipment by TrackingNumber.

ℹ Usage Note: The Track Request API should be used to look up tracking information for individual shipments on an ad-hoc basis. Each package may be tracked once per hour (24 times per day).

Possible tracking event codes and statuses include:

50 Shipment Data Uploaded
60 Shipment inventory allocated
75 Shipment Processed
80 Shipment Fulfilled
90 Shipment held for payment
100 Shipment information transmitted to carrier
125 Customs Cleared
135 Customs Issue
150 Crossing Border
155 Crossing Received
200 Item scanned at postal facility
225 Item grouped at Landmark or partner facility
250 Item scanned for crossing
275 Item in transit with carrier
300 Item out for delivery
400 Attempted delivery
410 Item available for pickup
450 Item re-directed to new address
500 Item successfully delivered
550 Return Received
800 Claim Issued
900 Delivery failed

SecuritybasicAuth

Request

query Parameters

Reference	string
TrackingNumber	string Example: TrackingNumber=LTN123121
PackageReference	string
RetrievalType	string Optional. Will return all tracking statuses for a package if populated. Will return last tracking status if empty or not present. Example: RetrievalType=Historical

Responses

200

Shipment Track Response

400

Error response

401

Unauthorized

429

Application-level throttling response

get/shipment

Request samples

curl
Node.js
Python

Response samples

application/json

{"Result": {"Success": "true",
"ShipmentDetails": {"EndDeliveryCarrier": "Canada Post"
},
"Packages": [{"TrackingNumber": "1Z123971A4",
"LandmarkTrackingNumber": "LTN123121",
"TrackingURL": "https://track.amazon.co.uk/tracking/A12414424593",
"LandmarkTrackingURL": "https://track.landmarkglobal.com/?sid=329122N2",
"PackageReference": "",
"ExpectedDelivery": "01-02-09",
"Events": [{"Status": "Delivered",
"DateTime": "2019-01-01 13:21:45",
"Location": "Windsor, ON",
"EventCode": 500
}
]
}
]
}
}

Cancel Or Delete Shipment Using Reference Or TrackingNumber

This endpoint cancels a carrier label with Mercury. The Cancel API request unprocesses shipments and also has the option to delete them.

This request will void a label of a processed shipment. The label cannot be used to send a shipment after a successful CancelRequest and the client will not be charged for the shipment. Depending on the service used, there will be a different window to unprocess the shipment. After manifesting, however, no shipment can be unprocessed.

To delete the shipment in addition to unprocessing it, set the optional DeleteShipment parameter to true. Even if the shipment is already canceled(unprocessed), this parameter can still attempt to delete the shipment.

This would typically be used after a Create Shipment call, and before the package leaves the client's facility.

SecuritybasicAuth

Request

query Parameters

Reference	string Example: Reference=3245325
TrackingNumber	string Example: TrackingNumber=7237529100002194
DeleteShipment	boolean Example: DeleteShipment=true
Reason	string Required if deleting a shipment. Example: Reason=Consignee canceled shipment.

Responses

200

Shipment canceled and deleted.

400

Error response

401

Unauthorized

429

Application-level throttling response

delete/shipment

Request samples

curl
Node.js
Python

Response samples

application/json

{"Result": {"Success": "true",
"ResultMessage": "Successfully unprocessed and deleted shipment with reference 3245325"
}
}

Download Customs Documents

This endpoint returns customs documents for a given shipment in base64. Lookup is perfromed by Reference Or TrackingNumber Or PackageReference.

SecuritybasicAuth

Request

query Parameters

Reference	string
TrackingNumber	string Example: TrackingNumber=LTN123121
PackageReference	string

Responses

200

Customs documents retrieved successfully.

400

Error response

401

Unauthorized

429

Application-level throttling response

get/customsDocuments

Request samples

curl
Node.js
Python

Response samples

application/json

{"CustomsDocuments": [{"DocumentFormat": "PDF",
"Content": "base64 encoded PDF"
}
],
"ShipmentsInMRN": [{"Reference": "string",
"TrackingNumber": "LTN123121",
"PackageReference": "string"
}
]
}

Obtain charged Duty & VAT amounts.

This endpoint returns charged Duty & VAT amounts for a given outbound shipment in GBP. Lookup is perfromed by Reference Or TrackingNumber Or PackageReference.

SecuritybasicAuth

Request

query Parameters

Reference	string
TrackingNumber	string Example: TrackingNumber=LTN123121
PackageReference	string

Responses

200

Customs documents retrieved successfully.

400

Error response

401

Unauthorized

429

Application-level throttling response

get/chargedDutyVAT

Request samples

curl
Node.js
Python

Response samples

application/json

{"ImportDuty": 0,
"VAT": 0,
"TotalDutyVAT": 0
}

Create a Return Shipment

This endpoint creates a return shipment in Mercury and generates an EVRI label for the first mile delivery. This label is subsequently used for line-haul to the Netherlands.

SecuritybasicAuth

Request

Request Body schema: application/json

TrackingNumber required	string Tracking Number of the original outbound shipment.
LabelFormat	string Optional. Default is PDF. Also supports JPG, GIF, BMP and PNG.
LabelEncoding	string Optional. Default is "LINKS". LINKS - returns links to all labels which must be retrieved in tag. BASE64 - Base64 encoded label image is returned directly in the response in tag. BASE64COMPRESSED - GZcompressed and Base64 encoded label image is returned directly in the response in tag.
required	Array of objects Required for customs if the shipment will be crossing the border.
property name* additional property	string

Responses

200

Shipment Created Successfully

400

Error response

401

Unauthorized

429

Application-level throttling response

post/return

Request samples

Payload
curl
Node.js
Python

application/json

{"TrackingNumber": "LTN329122N2",
"LabelFormat": "PDF",
"LabelEncoding": "LINKS",
"Items": [{"Sku": "7224059",
"Quantity": 2
}
]
}

Response samples

application/json

{"Test": "true",
"Result": {"Success": "true",
"ResultMessage": "Shipment 3245325 was successfully imported.",
"Packages": [{"LabelLink": "https://api.landmarkglobal.com/download/get-label.php?hid=5SalTlxR8JkpE%2FCW4HxGD0ghMOXXA%2F0rebjGm9EeaVlkG58%3D_5KAZZsOEn9E4p5Sy",
"LabelImages": [{"LabelImage": "23987B3KD0LK211AF......"
}
],
"TrackingNumber": "LTN329122N2",
"LandmarkTrackingNumber": "LTN329122N2",
"TrackingURL": "https://www.evri.com/track/parcel/H043IA0000538341",
"LandmarkTrackingURL": "https://track.landmarkglobal.com/?sid=329122N2",
"PackageReference": "98233310"
}
]
}
}

Landed Cost

Endpoints related to landed cost calculation

Obtain Landed Cost for a shipment

This endpoint accepts shipment data and returns the amount of assessed UK duties and taxes in GBP.

SecuritybasicAuth

Request

Request Body schema: application/json

ShipmentInsuranceFreight required	number Amount charged for shipping and any insurance for the shipment. This value does not include the amount charged for purchased items (i.e. Item Unit Value).
ItemsCurrency required	string Pass the 3 character ISO 4217 code to represent the currency (i.e. USD, CAD).
required	Array of objects Line-item data.
RequiresVATRepresentation	boolean Default: true Optional, Whether or not to provide UK VAT representation for this package.

Responses

200

Landed Cost Calculation

400

Error response

401

Unauthorized

429

Application-level throttling response

post/landedCost

Request samples

Payload
curl
Node.js
Python

application/json

{"ShipmentInsuranceFreight": 25,
"ItemsCurrency": "EUR",
"Items": [{"Quantity": 2,
"UnitPrice": 93.99,
"HSCode": "640399.30.00",
"CountryOfOrigin": "CN"
}
]
}

Response samples

application/json

{"Test": false,
"Result": {"ResultMessage": "success",
"ImportDuty": 12.34,
"VAT": 89.21,
"TotalDutyVAT": 101.55
}
}