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 Required	`Order[]`	Array of orders returned from the call. See Order table

`Order`

Field Name	Type	Description
BillingAddress Conditionally Required	`Address`	Billing Address of the customer. If empty then shipping address address must be applied. See Address Table.
DeliveryAddress Conditionally Required	`Address`	Shipping Address of the customer. If empty then billing address must be applied. See Address Table.
OrderItems Required	`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 Required	`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 Required	`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 Required	`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.
PIIRedactionDays	`Short?`	Days after order is processed when PII data will get redacted - NULL / Not Supplied will never redact
LocationTag	`String`	Only used for MLI - Provide if location tag is provided from the channel.

`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`	Indicates if the line item is tax cost exclusive or not `True` - The line is tax cost inclusive `False` - The line is tax cost exclusive
UseChannelTax	`Boolean`	Indicates if the order should used channel provided tax information or should use Linnworks calculated tax. This can be used in case the channel doesn't provide any tax information. `True` - We will use the channel provided tax figures `False` - We will ignore the channel provided tax figures and use the customers tax settings in Linnworks.
IsService	`Boolean`	Indicates if the line item is a service or a real product. `True` - The item is a service and when the order is saved it will create a order line service that is not linked to a Linnworks SKU. `False` -The item is a real product and therefore will be linked to a Linnworks SKU if a match is found.
OrderLineNumber Required	`String`	Unique per order line number. Any orders with non unique or duplicates will not be saved.
SKU Required	`String`	SKU of the product (used for Mapping). Must not be empty.
PricePerUnit	`String`	Individual price per unit.
Qty Required	`String`	Quantity ordered, must be greater than zero.
TaxRate	`String`	Tax rate of the product.
LinePercentDiscount	`String`	Percentage line discount.
ItemTitle Conditionally Required	`String`	Title of the product. Required when IsService is true Item title must be unique across all service items.
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.
CancelStatus	String``	Cancellation status of the line item. Valid values: `NONE` - The order item will be downloaded into Linnworks. `CANCELLED` - If the order item exists in Linnworks, it will be split into a new order and cancelled. If all items are marked as cancelled it will cancel the original order. If it doesn't exist in Linnworks, it will be ignored. Currently only whole lines can be cancelled. Cancellation of partial line quantities is not supported.

`OrderItemOption`

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

`Extended Property`

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

`Note`

Field Name	Type	Description
Note Required	`String`	Note text, duplicates will be ignored.
NoteEntryDate Required	`DateTime`	Date of the note Format: `yyyy-MM-dd HH:mm:ssZ`.
NoteUserName Required	`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
		}
	]
}