Square GraphQL lets you query for data across supported Square graphs. The query examples in this topic show common reporting scenarios that demonstrate the power and ease of using GraphQL. You can copy the examples and run them in GraphQL Explorer.
The examples use variables and include fields for pagination. To page through data, provide the cursor returned in the response as the before or after argument in your next query. Some examples also use aliases to rename response fields.
To get the merchant ID for the merchantId variable, run the following query in GraphQL Explorer:
{ currentMerchant { id }
Note
To learn about GraphQL Explorer features and how to get set up to run queries, see GraphQL Explorer Overview. GraphQL Explorer also provides a set of sample queries that you can run.
Returns information about in-progress or completed payments made by a customer within a specified time range. This query also retrieves any refunds for the payment.
Query:
query GetPaymentHistory($merchantId: ID!, $customerId: ID!, $start: DateTime!, $end: DateTime!) { payments( filter: { merchantId: { equalToAnyOf: [$merchantId] } customerId: { equalToAnyOf: [$customerId] } createdAt: { gte: $start, lte: $end } status: { not: { equalToAnyOf: [FAILED, CANCELED] }} } first: 10 after: null ) { edges { payment: node { id status createdAt orderId totalMoney { amount } refunds { edges { refund: node { id createdAt status reason refundOrderId: orderId amountMoney { amount } } } } } } pageInfo { hasNextPage endCursor } } }
This example uses a refundOrderId alias to rename the orderId field in the response when it applies to orders created for a refund.
Query variables:
{
"merchantId": "8QJTJCEXAMPLE",
"customerId": "9HRM2DFVBH73GGXRW4DEXAMPLE",
"start": "2023-07-01T00:00:00+08:00",
"end": "2023-07-31T23:59:59+08:00"
}Example response:
{
"data": {
"payments": {
"edges": [
{
"payment": {
"id": "VmSa8q5dr9JR29Y8TA5R1I9CEREZY",
"status": "COMPLETED",
"createdAt": "2023-07-28T23:26:01.342Z",
"orderId": "KPhxQRU3NwrHBNp5Hf4nxDQONb4F",
"totalMoney": {
"amount": 2892
},
"refunds": {
"edges": []
}
}
},
{
"payment": {
"id": "dywT8pGJR17ucj22F6JcP0uqhuPZY",
"status": "COMPLETED",
"createdAt": "2023-07-22T20:23:52.490Z",
"orderId": "E8D6I6qzSXFSHRjjdaMc4yAMGg4F",
"totalMoney": {
"amount": 2251
},
"refunds": {
"edges": [
{
"refund": {
"id": "dywT8pGJR17ucj22F6JcP0uqhuPZY_u78I80eCsH57XBD73Uo0XJk98mMANeGwyacfqzljGwE",
"createdAt": "2023-07-23T13:05:58.577Z",
"status": "COMPLETED",
"reason": "Changed mind",
"refundOrderId": "MAdvqLzKQNkT5COXL6DSSOElud4F",
"amountMoney": {
"amount": 2251
},
}
}
]
}
}
},
{
"payment": {
"id": "JmHnGCjUhnu82XiloQahDLz864GZY",
"status": "COMPLETED",
"createdAt": "2023-07-07T15:20:28.051Z",
"orderId": "mPUi8sbS9IRyxzx1LLFuLgbeLf4F",
"totalMoney": {
"amount": 1310
},
"refunds": {
"edges": []
}
}
}
],
"pageInfo": {
"hasPreviousPage": false,
"startCursor": "eyJjcmVhdGVkQXQiOjE2OTA1ODY3NjEzNDIsImlkIjoiVm1TYThxNWRyOUpSMjlZOFRBNVIxSTlDRVJFWlkifQ"
}
}
}
}Returns the processing fees associated with completed orders that were closed in a specified time range. This query retrieves the fees from the Payment object that corresponds to the tender.
Query:
query GetProcessingFees($merchantId: ID!, $start: DateTime!, $end: DateTime!) { orders( filter: { merchantId: { equalToAnyOf: [$merchantId] } state: { equalToAnyOf: [COMPLETED] } closedAt: { startAt: $start, endAt: $end } } orderBy: closedAt_ASC first: 10 after: null ) { nodes { orderId: id location { businessName } closedAt tenders { id payment { paymentId: id orderAmount: amountMoney { amount } processingFees { feeAmount: amountMoney { amount } } } } } pageInfo { hasNextPage endCursor } } }
This example uses orderAmount and feeAmount aliases to rename the amountMoney fields in the response for easier identification.
Query variables:
{
"merchantId": "8QJTJCEXAMPLE",
"start": "2023-07-01T00:00:00+08:00",
"end": "2023-07-01T23:59:59+08:00"
}Note
The Payment object is the source of truth for processing fees, but not all order tenders explicitly include a payment. In this case, you can query the Payments graph using the returned tender.id values, which represent payment IDs.
Example response:
{
"data": {
"orders": {
"nodes": [
{
"orderId": "wmrlIHmeRVgxS3FBZvKxWf7FZd4F",
"location": {
"businessName": "SuperFast Car Wash - West Side"
},
"closedAt": "2023-07-01T08:01:44.798Z",
"tenders": [
{
"payment": {
"paymentId": "jPBd0VKCdY7Gk7hGemiHtirG4h7YY",
"orderAmount": {
"amount": 900
},
"processingFees": [
{
"feeAmount": {
"amount": 244
}
}
]
}
}
]
},
{
"orderId": "4M2OkyEBMFVGLfhP6hwFA6Yymc4F",
"location": {
"businessName": "SuperFast Car Wash - West Side"
},
"closedAt": "2023-07-01T08:11:25.024Z",
"tenders": [
{
"payment": {
"paymentId": "jrPNSEyPosaPBHlImHG69RmKLkRZY",
"orderAmount": {
"amount": 900
},
"processingFees": [
{
"feeAmount": {
"amount": 244
}
}
]
}
}
]
},
{
"orderId": "UqAB1edK5lp0sAxdK57ZP93mVd4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T08:20:52.601Z",
"tenders": [
{
"payment": {
"paymentId": "zN6CRiWrb8e2GdlSOjVnQ9Vwya9YY",
"orderAmount": {
"amount": 1350
},
"processingFees": [
{
"feeAmount": {
"amount": 361
}
}
]
}
}
]
},
{
"orderId": "sYr0y9eUZBoXd2dmXhjvDGOW0e4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T08:24:30.496Z",
"tenders": [
{
"payment": {
"paymentId": "JaHoTpbmK8dofR9cUheOJl9dQVcZY",
"orderAmount": {
"amount": 900
},
"processingFees": [
{
"feeAmount": {
"amount": 244
}
}
]
}
}
]
},
{
"orderId": "Egf3ckbtco1nS3qoRpm1vulBzc4F",
"location": {
"businessName": "SuperFast Car Wash - West Side"
},
"closedAt": "2023-07-01T09:00:20.319Z",
"tenders": [
{
"payment": {
"paymentId": "P7cReDzNFPSQzAdrBb75vTslmiTZY",
"orderAmount": {
"amount": 1350
},
"processingFees": [
{
"feeAmount": {
"amount": 361
}
}
]
}
}
]
},
{
"orderId": "wSd15zmsEOswJZxOymh052hdge4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T09:15:27.525Z",
"tenders": [
{
"payment": {
"paymentId": "vXYAuirx9MbGepF6eqJCfgJP1vRZY",
"orderAmount": {
"amount": 1350
},
"processingFees": [
{
"feeAmount": {
"amount": 361
}
}
]
}
}
]
},
{
"orderId": "ksrgV4JgYfPl3g6VXMs7K40E1g4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T09:28:07.519Z",
"tenders": [
{
"payment": {
"paymentId": "hso5aEnJtE4UMTf4suHuXKPRjJTZY",
"orderAmount": {
"amount": 2200
},
"processingFees": [
{
"feeAmount": {
"amount": 582
}
}
]
}
}
]
},
{
"orderId": "gsIEmrXRvrlm9JovSp2J5Wdeqf4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T09:46:08.806Z",
"tenders": [
{
"payment": {
"paymentId": "Xlp07yignKhSgJDbs61r5EbYalHZY",
"orderAmount": {
"amount": 1350
},
"processingFees": [
{
"feeAmount": {
"amount": 361
}
}
]
}
}
]
},
{
"orderId": "mPUi8sbS9IRyxzx1LLFuLgbeLf4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T10:20:28.262Z",
"tenders": [
{
"payment": {
"paymentId": "JmHnGCjUhnu82XiloQahDLz864GZY",
"orderAmount": {
"amount": 900
},
"processingFees": [
{
"feeAmount": {
"amount": 244
}
}
]
}
}
]
},
{
"orderId": "E8D6I6qzSXFSHRjjdaMc4yAMGg4F",
"location": {
"businessName": "SuperFast Car Wash - East Side"
},
"closedAt": "2023-07-01T10:23:52.661Z",
"tenders": [
{
"payment": {
"paymentId": "dywT8pGJR17ucj22F6JcP0uqhuPZY",
"orderAmount": {
"amount": 2200
},
"processingFees": [
{
"feeAmount": {
"amount": 582
}
}
]
}
}
]
}
],
"pageInfo": {
"hasNextPage": true,
"endCursor": "A6QNHBVUdRxNdh9NMDNVIyxJMvUH5JppJxBpqeaiFH8BbachDeVxZg0rtJIkZyI8ILJlZhv7WMRSIP0HmT8GqCu4eg7c0GtehDwF56W1EPCEJPK2ISzFTSfQIXMCQvrU3RuiGlPGIyn3fWQGcZTWV2Z8ktNyBtLcJ6bBoeyJVOo1lBmFLCN1PqrqnfZgCPFkC6SE6U9jUeN2ROUkiJvZGEN5aGqIWZXoREZioDi59gmUaeHsMS5BslmZ69mgfGdLWmSnbq4fjBpWTYNSDuiR8tXPvQMEKUPQB5zjqWam7l2xd23FBY1zhh4VpM"
}
}
}
}Returns app fees earned for completed payments and deducted for refunds during a specified time period.
Developers should run this query using the access token and merchant ID of each Square seller account to report on.
Query:
query GetAppFees($merchantId: ID!, $start: DateTime!, $end: DateTime!) { payments( filter: { merchantId: { equalToAnyOf: [$merchantId] } applicationDetails: { applicationId: { equalToAnyOf: ["<YOUR_APPLICATION_ID>"] } } createdAt: { gte: $start, lt : $end } status: { equalToAnyOf: [COMPLETED] } } last: 5 before: null ) { edges { payment: node { id createdAt orderId totalMoney { amount } appFeeMoney { amount } refunds { edges { refund: node { id createdAt status reason refundOrderId: orderId appFeeMoney { amount } } } } } } pageInfo { hasPreviousPage startCursor } } }
This example uses a refundOrderId alias to rename the orderId field in the response when it applies to orders created for a refund.
Query variables:
{
"merchantId": "8QJTJCEXAMPLE",
"start": "2023-07-01T00:00:00+08:00",
"end": "2023-07-31T23:59:59+08:00"
}Response example:
{
"data": {
"payments": {
"edges": [
{
"payment": {
"id": "B46dLg5ttodGX2owQ17bDQ20ywJZY",
"createdAt": "2023-07-19T18:42:49.994Z",
"orderId": "AuN8vzMGDDPF3t4TxmIedOLCjPEZY",
"totalMoney": {
"amount": 4539
},
"appFeeMoney": {
"amount": 45
},
"refunds": {
"edges": [
{
"refund": {
"id": "B46dLg5ttodGX2owQ17bDQ20ywJZY_3ruRHCLH0g4StSN8cBUpso0hQTGkmDEdcXESBQpEola",
"createdAt": "2023-07-22T18:52:26.277Z",
"status": "COMPLETED",
"reason": "Wrong size",
"refundOrderId": "0uwOozNqgn5wjOd3k9H0O6uMHODZY",
"appFeeMoney": {
"amount": 12
}
}
}
]
}
}
},
{
"payment": {
"id": "VmeGFbItwtkL0706kNffPvFNMuHZY",
"createdAt": "2023-07-19T18:42:09.432Z",
"orderId": "cg9VOkUr4KWmETwF3QnP46Nn4g4F",
"totalMoney": {
"amount": 5265
},
"appFeeMoney": {
"amount": 53
},
"refunds": {
"edges": []
}
}
},
{
"payment": {
"id": "5eTLZSd6NKKBaYmp2zjNb4W863cZY",
"createdAt": "2023-07-18T18:40:38.967Z",
"orderId": "Ua2MDoCDN7N0Jm2eaEjVV3XRlZ4F",
"totalMoney": {
"amount": 1201
},
"appFeeMoney": {
"amount": 12
},
"refunds": {
"edges": []
}
}
},
{
"payment": {
"id": "F6AYLeB5op1tURThsAjL35p5KgcZY",
"createdAt": "2023-07-18T18:40:13.904Z",
"orderId": "uFjj9rH07RcDXyoU9dB45N8sYi4F",
"totalMoney": {
"amount": 6589
},
"appFeeMoney": {
"amount": 66
},
"refunds": {
"edges": []
}
}
},
{
"payment": {
"id": "lI9tUpdkfkO1Afzu9P3P06IkdpSZY",
"createdAt": "2023-07-16T16:00:38.608Z",
"orderId": "uNHD13PltXlJnGwIpZApAhSrpd4F",
"totalMoney": {
"amount": 1810
},
"appFeeMoney": {
"amount": 18
},
"refunds": {
"edges": []
}
}
}
],
"pageInfo": {
"hasPreviousPage": true,
"startCursor": "eyJjcmVhdGVkQXQiOjE2OTUxNDg5Njk5OTQsImlkIjoiQjQ2ZExnNXR0b2RHWDJvd1ExN2JEUTIweXdKWlkifQ"
}
}
}
}Retrieves details about an order, including information about the associated customer, catalog items, and payment. Sellers might run this query if they want to collect order data and feed it into a different system or analytics software for reporting purposes.
Query:
query GetOrderDetails($merchantId: ID!, $orderId: ID!) { orders( filter: { id: { equalToAnyOf: [$orderId]} merchantId: { equalToAnyOf: [$merchantId]}} ) { nodes { id createdAt state lineItems { quantity itemVariation { merchantId name item { name } } modifiers { name } } location { id mcc } customer { id givenName familyName merchantId } totalMoney { amount currency } tenders { type location { id } payment { id createdAt totalMoney { amount currency } status } } } } }
Query variables:
{
"merchantId": "8QJTJCEXAMPLE",
"orderId": "iMeAitUEv0KH1CAh6Nc2EXAMPLE"
}Example response:
{
"data": {
"orders": {
"nodes": [
{
"id": "EO8AHojRItAF3iltUZ1lM46ulf4F",
"createdAt": "2023-10-12T20:09:18.469Z",
"state": "COMPLETED",
"lineItems": [
{
"quantity": "1",
"itemVariation": {
"merchantId": "8QJTJCE6AZSN6",
"name": "Sm",
"item": {
"name": "Ice cream"
}
},
"modifiers": [
{
"name": "Rainbow sprinkles"
}
]
},
{
"quantity": "1",
"itemVariation": {
"merchantId": "8QJTJCE6AZSN6",
"name": "Lg",
"item": {
"name": "Ice cream"
}
},
"modifiers": [
{
"name": "Chocodip"
}
]
},
{
"quantity": "1",
"itemVariation": {
"merchantId": "8QJTJCE6AZSN6",
"name": "Lg",
"item": {
"name": "Ice cream"
}
},
"modifiers": [
{
"name": "Crunchy nuggets"
}
]
}
],
"location": {
"id": "M8AKAD8160XGR",
"mcc": "7299"
},
"customer": {
"id": "Q8002MMFCR5P0HJDGP30K0FRXM8BBZG",
"givenName": "Sara",
"familyName": "Vera",
"merchantId": "8QJTJCE6AZSN6"
},
"totalMoney": {
"amount": 2279,
"currency": "USD"
},
"tenders": [
{
"type": "CARD",
"location": {
"id": "M8AKAD8160XGR"
},
"payment": {
"id": "Ln3bweFoAyrpnhF1QV5Jmh3Kn3EZY",
"createdAt": "2023-10-12T20:09:20.128Z",
"totalMoney": {
"amount": 2279,
"currency": "USD"
},
"status": "COMPLETED"
}
}
]
}
]
}
}
}