This call is made by Linnworks automation to get a list of orders since the last time it requested orders. These calls are made every 10 to 15 minutes usually. The request expects a page result back, if there are a lot of orders to return it is suggested to split the result into pages of 100 maximum.

Request

Post

`OrdersRequest`

Field Name	Type	Description
AuthorizationToken	`String`	Authorization Token from the customers integration.
UTCTimeFrom	`DateTime`	Utc date from Linnworks since the last time we had a successful orders request. This may change from Linnworks side if the user want’s to back date the sync. It is suggested that if the channels API has the availability of filtering by the last time the order was updated to use this. Format: `yyyy-MM-dd HH:mm:ssZ`
PageNumber	`Int`	Page number of the request. Starts from 1.

Sample

{
  "AuthorizationToken": "f989a881a6a241d5ab81b4b03f3730f1",
  "UTCTimeFrom": "2023-08-26T09:43:14Z",
  "PageNumber": 1
}

Response

`OrdersResponse`

Field Name	Type	Description
Error	`String`	If there was an error with the request.
HasMorePages	`Order[]`	Array of orders returned from the call. See Order table

`Order`

Field Name	Type	Description
BillingAddress	`Address`	Billing Address of the customer. See Address Table.
DeliveryAddress	`Address`	Shipping Address of the customer. See Address Table.
OrderItems	`OrderItem[]`	Array of order items relating to the order. See OrderItem Table.
ExtendedProperty	`ExtendedProperty[]`	Array of order extended properties relating to the order. Names should be unique as they are used as a key. See ExtendedProperty table
Notes	`Note[]`	Array of order notes relating to the order. See Notes table.
Site	`String`	Site of the order, this is usually used when the channel has one set of credentials however has multiple sites for example UK, DE, US and so on. Leave blank if this is not applicable. This field is used in Postal Service and Payment mapping.
MatchPostalServiceTag	`String`	Shipping tag used which is used for order mapping to map the channel shipping tag to the Linnworks shipping service.
MatchPaymentMethodTag	`String`	Payment tag used which is used for order mapping to map the channel payment tag to the Linnworks payment service.
PaymentStatus	`String`	Payment status of the order. Valid values: `PAID` - The order will be downloaded as a paid order in Linnworks `UNPAID` - The order will be downloaded as an unpaid order in Linnworks `CANCELLED` - If the order exists in Linnworks, it will be marked as cancelled. If it doesn't exist in Linnworks, it will be ignored
ChannelBuyerName	`String`	Name of the customer who bought the item. If the channel supports usernames it’s suggested to put the username instead of the actual name of the customer.
ReferenceNumber	`String`	Unique reference of the order. If two orders have the same reference then one will be ignored. This field will be sent back when marking orders as despatched.
ExternalReference	`String`	External reference is usually the payment gateway transaction id.
Currency	`String`	3 digit ISO 4217 currency code of the order.
ReceivedDate	`DateTime`	Date the order was created. Where possible normalize to UTC Format: `yyyy-MM-dd HH:mm:ssZ`.
DispatchBy	`DateTime`	Date the order should be shipped by. Where possible normalize to UTC Format: `yyyy-MM-dd HH:mm:ssZ`.
PaidOn	`DateTime`	Date the order was paid. Where possible normalize to UTC Format: `yyyy-MM-dd HH:mm:ssZ`.
PostalServiceCost	`Decimal`	Postal cost of the order including tax.
PostalServiceTaxRate	`Decimal`	Tax rate used for the postal service.
UseChannelTax	`Boolean`	If True Linnworks will not overwrite the PostalServiceTaxRate percentage.
DiscountType	`String`	Discount type of the order. Valid values: `AllEvenly` - The given discount amount will be split evenly across all items and any applicable postage. `ItemsThenPostage` - The discount amount will be split evenly across all items. Any remaining discount will be applied to the postage where applicable. `PostageThenItems` - he discount amount will be applied to the postage cost where applicable. Any remaining discount will be split evenly across all items.
Discount	`Decimal`	The amount of discount.
MarketplaceTaxId	`String`	Marketplace Tax Id.
BuyerTaxNumber	`String`	Tax number of buyer.

`Address`

Field Name	Type	Description
FullName	`String`	Customer Full Name.
Company	`String`	Customer Company.
Address1	`String`	First line of address.
Address2	`String`	Second line of address.
Address3	`String`	Third line of address.
Town	`String`	Town.
Region	`String`	Area, County, State or Region.
PostCode	`String`	Postal / Zip Code.
Country	`String`	Country
CountryCode	`String`	ISO 3166-2 Country Code.
PhoneNumber	`String`	Customer's phone number.
EmailAddress	`String`	Email Address.

`OrderItem`

Field Name	Type	Description
TaxCostInclusive	`Boolean`	Customer Full Name.
UseChannelTax	`Boolean`	Customer Company.
IsService	`Boolean`	First line of address.
OrderLineNumber	`String`	Unique per order line number. Any orders with non unique or duplicates will not be saved.
SKU	`String`	SKU of the product (used for Mapping). Must not be empty.
PricePerUnit	`String`	Individual price per unit.
Qty	`String`	Quantity ordered
TaxRate	`String`	Tax rate of the product.
LinePercentDiscount	`String`	Percentage line discount.
ItemTitle	`String`	Title of the product.
Options	`OrderItemOption[]`	Order item options, usually used for customizations. Name must not exist multiple times as it's used as a key. See OrderItemOption Table.

`OrderItemOption`

Field Name	Type	Description
Name	`String`	Unique per order option Name.
Value	`String`	Option Value.

`Extended Property`

Field Name	Type	Description
Name	`String`	Unique per order option Name.
Value	`String`	Property value.
Type	`String`	Type of property for example "Shipping", "Tracking Number".

`Note`

Field Name	Type	Description
Note	`String`	Note text, duplicates will be ignored.
NoteEntryDate	`DateTime`	Date of the note Format: `yyyy-MM-dd HH:mm:ssZ`.
NoteUserName	`String`	User who entered the note, if left blank `Channel` will be entered.
IsInternal	`Boolean`	Indicates if the note is customer visible. For example if set to True then it will not be printed on an invoice

Sample

{
	"Error": null,
	"HasMorePages": true,
	"Orders": [
		{
			"BillingAddress": {
				"FullName": "Mr Billing Billington",
				"Company": "Linn Systems Ltd",
				"Address1": "2-4 Southgate",
				"Address2": "",
				"Address3": "",
				"Town": "Chichester",
				"Region": "West Sussex",
				"PostCode": "PO19 8DJ",
				"Country": "United Kingdom",
				"CountryCode": "GB",
				"PhoneNumber": "00000000002",
				"EmailAddress": "[email protected]"
			},
			"DeliveryAddress": {
				"FullName": "Mr Testing Testington",
				"Company": "Linn Systems Ltd",
				"Address1": "2-4 Southgate",
				"Address2": "",
				"Address3": "",
				"Town": "Chichester",
				"Region": "West Sussex",
				"PostCode": "PO19 8DJ",
				"Country": "United Kingdom",
				"CountryCode": "GB",
				"PhoneNumber": "00000000001",
				"EmailAddress": "[email protected]"
			},
			"OrderItems": [
				{
					"TaxCostInclusive": true,
					"UseChannelTax": false,
					"IsService": false,
					"OrderLineNumber": "0",
					"SKU": "ChannelProduct_0",
					"PricePerUnit": 0.731495563281465,
					"Qty": 479904921,
					"TaxRate": 20.0,
					"LinePercentDiscount": 0.0,
					"ItemTitle": "Title for MyReference-2ChannelProduct_0",
					"Options": [
						{
							"Name": "Colour",
							"Value": "Red"
						}
					]
				}
			],
			"ExtendedProperties": [
				{
					"Name": "Prop0",
					"Value": "Val0",
					"Type": "Info"
				}
			],
			"Notes": [
				{
					"Note": "A customer has left a note",
					"NoteEntryDate": "2016-08-26T13:28:05Z",
					"NoteUserName": "Channel",
					"IsInternal": false
				}
			],
			"Site": "",
			"MatchPostalServiceTag": "Royal Mail First Class",
			"MatchPaymentMethodTag": "PayPal",
			"PaymentStatus": "PAID",
			"ChannelBuyerName": "A Channel Buyer Name",
			"ReferenceNumber": "MyReference-2",
			"ExternalReference": "MyExternalReference-1",
			"SecondaryReferenceNumber": null,
			"Currency": "GBP",
			"ReceivedDate": "2016-08-26T13:23:05.1678193Z",
			"DispatchBy": "2016-09-05T13:28:05.1678193Z",
			"PaidOn": "2016-08-26T13:19:05.1678193Z",
			"PostalServiceCost": 0.818234497130958,
			"PostalServiceTaxRate": 20.0,
			"UseChannelTax": false
		}
	]
}