Make common queries with the Billing API
You can use the following examples to familiarize yourself with the Billing API data.
Query for an AppPurchase
Using the Billing API you can query for an individual purchase or query for multiple purchases.
Query for multiple purchases
To query for multiple purchases, you can use the currentAppInstallation type. You can use the first or last argument to specify how many purchases you want to return.
query {
currentAppInstallation {
oneTimePurchases(first: 2) {
edges {
node {
...on AppPurchaseOneTime {
price {
amount
currencyCode
}
createdAt
id
name
status
test
}
}
}
}
}
}JSON response:
{
"data": {
"currentAppInstallation": {
"oneTimePurchases": {
"edges": [
{
"node": {
"price": {
"amount": "100.0",
"currencyCode": "USD"
},
"createdAt": "2017-11-01T19:17:09Z",
"id": "gid://shopify/AppPurchaseOneTime/5308422",
"name": "Super Duper Expensive action",
"status": "ACTIVE",
"test": true
}
},
{
"node": {
"price": {
"amount": "100.0",
"currencyCode": "USD"
},
"createdAt": "2017-11-02T18:22:00Z",
"id": "gid://shopify/AppPurchaseOneTime/5701638",
"name": "Another Super Duper Expensive action",
"status": "EXPIRED",
"test": true
}
}
]
}
}
},
...
}Query for a single purchase
To query for a single purchase, you can query the node on AppPurchaseOneTime by passing the app purchase's ID as an argument.
query {
node(id: "gid://shopify/AppPurchaseOneTime/5308422"){
... on AppPurchaseOneTime {
price {
amount
currencyCode
}
createdAt
id
name
status
test
}
}
}JSON response:
{
"data": {
"node": {
"price": {
"amount": "100.0",
"currencyCode": "USD"
},
"createdAt": "2017-11-01T19:17:09Z",
"id": "gid://shopify/AppPurchaseOneTime/5308422",
"name": "Super Duper Expensive action",
"status": "ACTIVE",
"test": true
}
},
...
}Query for an AppSubscription
Using the Billing API you can query for an individual subscription or query for multiple subscriptions.
Query for multiple subscriptions
To query for multiple subscriptions, you can use the currentAppInstallation type. You can use the first or last argument to specify how many to return.
query {
currentAppInstallation {
rawSubscriptions(first: 2) {
edges {
node {
lineItems {
plan {
pricingDetails {
__typename
... on AppRecurringPricing {
price {
amount
currencyCode
}
}
... on AppUsagePricing {
balanceUsed {
amount
currencyCode
}
cappedAmount {
amount
currencyCode
}
}
}
}
}
createdAt
id
name
status
test
}
}
}
}
}JSON response:
{
"data": {
"currentAppInstallation": {
"rawSubscriptions": {
"edges": [
{
"node": {
"lineItems": [
{
"plan": {
"pricingDetails": {
"__typename": "AppRecurringPricing",
"price": {
"amount": "4.99",
"currencyCode": "USD"
}
}
}
},
{
"plan": {
"pricingDetails": {
"__typename": "AppUsagePricing",
"balanceUsed": {
"amount": "0.0",
"currencyCode": "USD"
},
"cappedAmount": {
"amount": "100.0",
"currencyCode": "USD"
}
}
}
}
],
"createdAt": "2016-08-30T17:00:16Z",
"id": "gid://shopify/AppSubscription/2816132",
"name": "Gift Basket Plan",
"status": "EXPIRED",
"test": true
}
},
{
"node": {
"lineItems": [
{
"plan": {
"pricingDetails": {
"__typename": "AppRecurringPricing",
"price": {
"amount": "4.99",
"currencyCode": "USD"
}
}
}
},
{
"plan": {
"pricingDetails": {
"__typename": "AppUsagePricing",
"balanceUsed": {
"amount": "0.0",
"currencyCode": "USD"
},
"cappedAmount": {
"amount": "100.0",
"currencyCode": "USD"
}
}
}
}
],
"createdAt": "2016-09-21T19:42:43Z",
"id": "gid://shopify/AppSubscription/2962896",
"name": "Gift Basket Plan",
"status": "EXPIRED",
"test": true
}
}
]
}
}
},
...
}Query for a single subscription
To query for a single subscription, you can query the node on AppSubscription by passing the app purchase's ID as an argument.
query {
node(id: "gid://shopify/AppSubscription/4019585080") {
...on AppSubscription {
billingInterval
createdAt
currentPeriodEnd
id
name
status
test
lineItems {
plan {
pricingDetails {
...on AppRecurringPricing {
interval
price {
amount
currencyCode
}
}
...on AppUsagePricing {
terms
cappedAmount {
amount
currencyCode
}
balanceUsed {
amount
currencyCode
}
}
}
}
}
}
}
}JSON response:
{
"data": {
"node": {
"billingInterval": "EVERY_30_DAYS",
"createdAt": "2019-05-30T15:50:50Z",
"currentPeriodEnd": null,
"id": "gid://shopify/AppSubscription/4019585080",
"name": "Super Duper Capped Pricing Plan",
"status": "CANCELLED",
"test": true,
"lineItems": [
{
"plan": {
"pricingDetails": {
"terms": "$1 for 100 emails",
"cappedAmount": {
"amount": "20.0",
"currencyCode": "USD"
},
"balanceUsed": {
"amount": "0.0",
"currencyCode": "USD"
}
}
}
}
]
}
},
...
}Query for AppUsageRecords
To query for AppUsageRecords, you can use the currentAppInstallation type. You can obtain the usageRecords from the lineItems field of rawSubscriptions. You can use the first or last argument to specify how many to return.
query {
currentAppInstallation {
rawSubscriptions(first: 2) {
edges {
node {
id
status
lineItems {
id
usageRecords(first: 5) {
edges {
node {
id
description
createdAt
price {
amount
currencyCode
}
}
}
}
}
}
}
}
}
}JSON response:
{
"data": {
"currentAppInstallation": {
"rawSubscriptions": {
"edges": [
{
"node": {
"id": "gid://shopify/AppSubscription/2816132",
"status": "EXPIRED",
"lineItems": [
{
"id": "gid://shopify/AppSubscriptionLineItem/2816132?v=1&index=0",
"usageRecords": {
"edges": []
}
},
{
"id": "gid://shopify/AppSubscriptionLineItem/2816132?v=1&index=1",
"usageRecords": {
"edges": []
}
}
]
}
},
{
"node": {
"id": "gid://shopify/AppSubscription/2962896",
"status": "EXPIRED",
"lineItems": [
{
"id": "gid://shopify/AppSubscriptionLineItem/2962896?v=1&index=0",
"usageRecords": {
"edges": []
}
},
{
"id": "gid://shopify/AppSubscriptionLineItem/2962896?v=1&index=1",
"usageRecords": {
"edges": []
}
}
]
}
}
]
}
}
},
...
}Query for AppUsageRecords for a specific subscription
To query for an AppUsageRecord on a specific subscription, you can query the node on AppSubscription by passing the app subscription ID as an argument.
query {
node(id: "gid://shopify/AppSubscription/4019585080"){
...on AppSubscription {
lineItems {
usageRecords(first: 5) {
edges {
node {
id
description
createdAt
price {
amount
currencyCode
}
}
}
}
}
}
}
}JSON response:
{
"data": {
"node": {
"lineItems": [
{
"usageRecords": {
"edges": [
{
"node": {
"id": "gid://shopify/AppUsageRecord/14518231",
"description": "Super Mega Plan 1000 emails",
"createdAt": "2019-05-30T16:03:31Z",
"price": {
"amount": "1.0",
"currencyCode": "USD"
}
}
}
]
}
}
]
}
},
...
}Query for a specific AppUsageRecord by ID
To query for a specific app usage record, you can query the node on AppUsageRecord by passing the app usage record ID as an argument.
query {
node(id: "gid://shopify/AppUsageRecord/14518231"){
...on AppUsageRecord {
createdAt
description
id
price {
amount
currencyCode
}
}
}
}JSON response:
{
"data": {
"node": {
"createdAt": "2019-05-30T16:03:31Z",
"description": "Super Mega Plan 1000 emails",
"id": "gid://shopify/AppUsageRecord/14518231",
"price": {
"amount": "1.0",
"currencyCode": "USD"
}
}
},
...
}