Marketplaces / Tesco (on Marketplacer) / Tesco Technical Scope / Tesco Order Management / Tesco Get Orders

Tesco Get Orders

Version	Date	Created / Updated	Notes
v1.0	04/01/2025	Hristiyan Georgiev	Initial version
v1.1	04/29/2025	Hristiyan Georgiev	Payload and mapping changes
v1.2	05/21/2025	Hristiyan Georgiev	Changed logic and mapping on Total and Subtotal amounts.

The Tesco Order Model

The diagram below illustrates the relationship between Order, Invoices and Line Items:

Put simply:

A Seller is an individual entity (usually a business) that the marketplace operator has invited to sell on their marketplace. Multiple sellers can “participate” in a single order.
An Order is the “marketplace-level” object that acts as the container for a customer’s entire purchase. An order object in Tesco will always have at least 1 Invoice attached to it.
An invoice is the individual seller’s “view” of the order. Given that we are dealing with a marketplace, it is conceivable that customers will purchase items from 1 or more Sellers. It is therefore necessary to “split” the order into seller-level components, in this case the invoice object. Even if there is only 1 seller participating in the transaction, there will still be an invoice created on the order
A Line Item is the individual item that a customer will purchase. Line items start their journey as Variants placed for sale on the marketplace by the seller. When a variant object is purchased a lineItem object is created.

The primary takeaway from the above is that as a Seller on Tesco, we will primarily be interested in querying Invoice objects.

Get Orders

The first run will check for new orders in the last 90 days and afterwards we will get the date from last_date_run table and filter orders using a variable that will be explained below. We want to overlap the time with 1 hour, meaning that we should use the time of last_date_run - 1 hour.

API Docs : https://api.marketplacer.com/docs/seller-api/examples/orders/invoices/

<v1.1>GraphQL Query :

query GetInvoicesCreatedSince($pageSize: Int $endCursor: String, $filters: InvoiceFilters){
  invoices(first : $pageSize, after: $endCursor filters: $filters){
    pageInfo{        
        hasNextPage
        endCursor
        }
        totalCount
        nodes{
            legacyId
            id
            statusFlags
            buyerFirstName
            buyerSurname
            buyerPhone
            buyerEmailAddress
            buyerMessageToSeller            
            shippingAddress {
                address
                city
                country {
                    name
                    code
                }
                postcode
                state {
                    name
                }
            } 
             buyerBillingAddress {
                    address
                city
                country {
                    name
                    code
                }
                postcode
                state {
                    name
                }   

            }
            createdAt
            deliveryType
            statusFlags
            paidAt
            shipments {      
                id          
                dispatchedAt
                carrier
                trackingNumber
                trackingLink
                shippedItems{
                    quantity
                    lineItem{
                        id
                    }
                 }               
             }
             totalFormatted(currency: "GBP")
             subtotalFormatted(currency: "GBP")
             shippingCostFormatted(currency: "GBP")
             taxShippingFormatted(currency: "GBP")
             taxTotalFormatted(currency: "GBP")             
            lineItems{
                id
                advertTitle
                variantBarcode
                variantId
                variantSku
                variantName
                legacyId
                quantity
                itemAmountFormatted(currency: "GBP")                
                postageFormatted(currency: "GBP")
                taxTotalFormatted(currency: "GBP")
                taxShippingFormatted(currency: "GBP")                
            }

             updatedAt
        }
    }
}

Please note that we are not querying for any refund related stuff in the Get Orders call as this will be handled with the Get Claims functionality </v1.1>

We need to pick the currency from Account > Exchange Rate Calculator Currency as this will be the currency in which the information for the order will be returned for.

Query Variables :

{
    "pageSize": 50,
    "endCursor": null,
    "filters": {
        "createdSince": "2024-10-16T09:58:00"
    }
}

Variables Mapping :

Integration FIeld		Hemi Notes
`pageSize`		This will be our page size for this query
`endCursor`		Should be null when doing the first query, and then if in the response we have `hasNextPage` = true, we need to use the string returned in the `endCursor` field.
`filters`
	`createdSince`	`last_date_run` - 1hour

Should be in a ISO8601 date format : 2024-10-16T09:58:00 |

Example response (please note that for the sake of mapping this is a full case scenario response, with a shipped and refunded order. In most cases when we are getting brand new orders, we will have empty shipments and refundrequests objects) :

{
    "data": {
        "invoices": {
            "pageInfo": {
                "hasNextPage": true,
                "endCursor": "MQ"
            },
            "totalCount": 27,
            "nodes": [
                {
                    "legacyId": 13913,
                    "id": "SW52b2ljZS0xMzkxMw==",
                    "statusFlags": [
                        "PAID",
                        "SENT",
                        "AWAITING_RETURN"
                    ],
                    "buyerFirstName": "Erling",
                    "buyerSurname": "Boehm",
                    "buyerPhone": "0405510001",
                    "buyerEmailAddress": "hs@email.com",
                    "buyerMessageToSeller": null,
                    "shippingAddress": {
                        "address": "35 Collins Street",
                        "city": "Sydney",
                        "country": {
                            "name": "Australia",
                            "code": "AU"
                        },
                        "postcode": "2000",
                        "state": {
                            "name": "New South Wales"
                        }
                    },
                    "buyerBillingAddress": {
                        "address": "35 Collins Street",
                        "city": "Sydney",
                        "country": {
                            "name": "Australia",
                            "code": "AU"
                        },
                        "postcode": "2000",
                        "state": {
                            "name": "New South Wales"
                        }
                    },
                    "createdAt": "2024-10-16T09:58:22+11:00",
                    "deliveryType": "BUY_ONLINE",
                    "paidAt": "2024-10-16T09:58:23+11:00",
                    "shipments": [
                        {
                            "id": "U2hpcG1lbnQtMTAzNA==",
                            "dispatchedAt": "2024-10-23T22:13:27+11:00",
                            "carrier": "DHL",
                            "trackingNumber": "9887456321",
                            "trackingLink": "http://www.dhl.com.au/en/express/tracking.html?brand=DHL&AWB=9887456321",
                            "shippedItems": [
                                {
                                    "quantity": 1,
                                    "lineItem": {
                                        "id": "TGluZUl0ZW0tNDMyNQ=="
                                    }
                                }
                          ]
                       }         
                    ],
                    "totalFormatted": "£50.23",
                    "subtotalFormatted": "£50.23",
                    "shippingCostFormatted": "£0.00",
                    "taxShippingFormatted": "£0.00",
                    "taxTotalFormatted": "£0.00",
                    "lineItems": [
                        {
                            "id": "TGluZUl0ZW0tNDMyNQ==",
                            "advertTitle": "Electronic Rubber Cheese",
                            "variantBarcode": null,
                            "variantId": "VmFyaWFudC0xMDU0Njc=",
                            "variantSku": "LnYy",
                            "variantName": "blue / Navy",
                            "legacyId": 4325,
                            "quantity": 1,
                            "itemAmountFormatted": "£50.23",
                            "postageFormatted": "£0.00",
                            "taxTotalFormatted": "£0.00"
                        }
                    ],
                    "updatedAt": "2024-10-23T23:41:07+11:00"
                }
            ]
        }
    }
}

Response Mapping (<v1.1> the changes here are that refund related mapping was removed, also one of the existing fields was changed </v1.1>) :

Integration Field				Hemi Mapping
`data`
	`invoices`
		`pageInfo`
		`hasNextPage`		N/A
		`endCursor`		N/A
		`totalCount`
		`nodes`
			`legacyId`	`Orders` > `Selling Manager SalesRecordNumber`
			`id`	`Orders` > `Marketplace Order ID`
			`statusFlags`	`Orders` > `Status`

Order Statuses

Tesco Order Status	Description	Hemi Status	Notes
AWAITING_REFUND	A Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested and items have been marked as having been returned to the Seller. The refund request is awaiting the Operator to either approve or deny the refund request.	N/A	We always want to check the previous status in `statusFlags` that we have mapping for and set the Hemi status to the last mapped status. Incase we receive this for a brand new order, again we check for the previous status in `statusFlags` in the response and map it to the relevant MC Pro status.
AWAITING_RETURN	A Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested. The refund request is awaiting on the Seller to mark the items as having been returned in acceptable condition.	N/A	We always want to check the previous status in `statusFlags` that we have mapping for and set the Hemi status to the last mapped status. Incase we receive this for a brand new order, again we check for the previous status in `statusFlags` in the response and map it to the relevant MC Pro status.
CANCELLED	[Non-Connected Only] Order / Invoice had been awaiting payment but the payment has subsequently been cancelled.	Cancelled
COLLECTED	[Non-Connected Only] Where a click and collect order / invoice had been placed, and the line items on that invoice had been collected. At the time of writing Click and Collect functionality is only available in Non-Connected instances.	Shipped
PAID	Order has been completed and payment has been “processed”. This includes US-based scenarios where delayed payment capture is being used.	Ready for Shipping
PARTIALLY_SENT	Only some items of an invoice have been dispatched. This includes scenarios where: 1) Multiple quantities of a single line item were ordered and only a subset have been dispatched, 2) Multiple line items had been ordered and only some of those line items have been dispatched	Partially Shipped
PAYMENT_UNDER_REVIEW	[Non-Connected Only] Where payments are being taken by Tesco the payment gateway has placed the payment in a review status.	Pending	We dont want to store payment row on this status
READY	[Non-Connected Only] Where a click and collect order / invoice has been placed, and the items on that invoice are ready to be collected. At the time of writing click and collect functionality is only available in Non-Connected instances.	Ready for Shipping
REFUNDED	A Cancellation (pre-dispatch) or Return (Post-dispatch), has been requested and approved.	Cancelled
REMITTED	Remittance has been paid to the seller of this Invoice.	N/A	We always want to check the previous status in `statusFlags` that we have mapping for and set the Hemi status to the last mapped status. Incase we receive this for a brand new order, again we check for the previous status in `statusFlags` in the response and map it to the relevant MC Pro status.
SENT	All line items on the invoice have been sent.	Shipped

Get Modified Orders

We want to have the functionality to get info on modified orders. The GraphQL Query is the same as the Get orders one, the only difference will be in the variables where we need to change the createdSince variable with updatedSince. The response and mapping are all the same as the Get Orders. We want to implement the last_date_run table for this cron too and it should search for orders with last_date_run - 30 minutes

Is this article helpful?

0 0 0