View example queries that show how to use Square GraphQL for common reporting scenarios.
Square GraphQL lets you query for data across supported Square graphs. The following query examples 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 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. GraphQL Explorer also provides a set of sample queries that you can run.
The following example 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 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.
The following example 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 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.
The following example returns application fees earned for completed payments and deducted for refunds during a specified time period.
You should run this query using the access token and merchant ID of each Square seller account you want to report on.
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.
The following example 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 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 } } } } }
The following example retrieves payout entries that contain CHARGE and REFUND fees for card payments during a specified time period.
This example queries the payoutEntries entry point.
query FetchPayoutEntries($merchantId: ID!, $start: DateTime, $end: DateTime) { payoutEntries( filter: { merchant: {id: {equalToAnyOf: [$merchantId]}} type: {equalToAnyOf: ["CHARGE","REFUND"]} effectiveAt: {gte: $start, lte: $end} } orderBy: [type_ASC, effectiveAt_ASC] first: 25 after: null ) { totalEdgeCount edges { node { id payoutId effectiveAt grossAmountMoney { amount currency } feeAmountMoney { amount currency } netAmountMoney { amount currency } type typeChargeDetails { paymentId } typeRefundDetails { paymentId refundId } } } pageInfo { hasNextPage endCursor } } }