We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Example queries

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
          }
        }
      }
    }
  }
}

View response

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
    }
  }
}

View response

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
        }
      }
    }
  }
}

View response

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
              }
            }
          }
        }
      }
    }
  }
}

View response

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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

View response

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
              }
            }
          }
        }
      }
    }
  }
}

View response

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
      }
    }
  }
}

View response

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"
      }
    }
  },
  ...
}

Sign up for a Partner account to get started.

Sign up