BackgroundPrimary care has been described as the ‘bedrock’ of the National Health Service (NHS) accounting for approximately 90% of patient contacts but is facing significant challenges. Against a backdrop of a rapidly ageing population with increasingly complex health challenges, policy-makers have encouraged primary care commissioners to increase the usage of data when making commissioning decisions. Purported benefits include cost savings and improved population health. However, research on evidence-based commissioning has concluded that commissioners work in complex environments and that closer attention should be paid to the interplay of contextual factors and evidence use. The aim of this review was to understand how and why primary care commissioners use data to inform their decision making, what outcomes this leads to, and understand what factors or contexts promote and inhibit their usage of data.MethodsWe developed initial programme theory by identifying barriers and facilitators to using data to inform primary care commissioning based on the findings of an exploratory literature search and discussions with programme implementers. We then located a range of diverse studies by searching seven databases as well as grey literature. Using a realist approach, which has an explanatory rather than a judgemental focus, we identified recurrent patterns of outcomes and their associated contexts and mechanisms related to data usage in primary care commissioning to form context-mechanism-outcome (CMO) configurations. We then developed a revised and refined programme theory.ResultsNinety-two studies met the inclusion criteria, informing the development of 30 CMOs. Primary care commissioners work in complex and demanding environments, and the usage of data are promoted and inhibited by a wide range of contexts including specific commissioning activities, commissioners’ perceptions and skillsets, their relationships with external providers of data (analysis), and the characteristics of data themselves. Data are used by commissioners not only as a source of evidence but also as a tool for stimulating commissioning improvements and as a warrant for convincing others about decisions commissioners wish to make. Despite being well-intentioned users of data, commissioners face considerable challenges when trying to use them, and have developed a range of strategies to deal with ‘imperfect’ data.ConclusionsThere are still considerable barriers to using data in certain contexts. Understanding and addressing these will be key in light of the government’s ongoing commitments to using data to inform policy-making, as well as increasing integrated commissioning.Supplementary InformationThe online version contains supplementary material available at 10.1186/s12916-023-02949-w.