Get raw Shopify GraphQL contract response
Returns a subscription contract as Shopify stores it, read from Shopify on every call: its status, dates, billing and delivery policy, lines, discounts, delivery price, delivery address and method, payment method, customer and origin order. This is an Admin API endpoint: call it from your server, never from a storefront or the customer’s browser.
The response has a fixed set of fields, not every field Shopify has, and every object carries its __typename. Lists hold only their first items: up to 50 lines by default, 25 discounts and 20 originOrder.fulfillmentOrders. Each of these three has a pageInfo object, and pageInfo.hasNextPage is true when there are more, but this call takes no cursor. billingAttempts holds only the latest attempt and has no pageInfo.
Delivery address and method
deliveryMethod is null when the contract has nothing to ship. Otherwise deliveryMethod.__typename says how the contract is delivered, and the fields that follow depend on it:
SubscriptionDeliveryMethodShipping:addressandshippingOption. The option hastitle,presentmentTitle,descriptionandcode.SubscriptionDeliveryMethodLocalDelivery:addressandlocalDeliveryOption, withtitle,presentmentTitle,description,codeandphone.SubscriptionDeliveryMethodPickup:pickupOptiononly, withtitle,presentmentTitle,description,codeand itslocation(id,nameandaddress). There is no customer address. The location’saddresshasaddress1,address2,city,country,countryCode,phone,province,provinceCodeandzip.
address has address1, address2, city, company, country, countryCode, countryCodeV2, firstName, lastName, name, phone, province, provinceCode and zip. The contract list from GET /api/external/v2/subscription-contract-details has none of them, only deliveryCountryCode.
The type comes from how Shopify delivers the order, not from the rate’s name: a shipping rate called “Free store pickup” is still SubscriptionDeliveryMethodShipping.
To change the address or method, call PUT /api/external/v2/subscription-contracts-update-shipping-address (address and methodType) or PUT /api/external/v2/subscription-contracts-update-delivery-method (the shipping option).
When to use it
Use this call when you need Shopify’s own contract data, such as the delivery address and method or the discount IDs. For a list of contracts, or when speed matters, use GET /api/external/v2/subscription-contract-details: this call waits for Shopify, and it counts against the store’s Shopify API limits, so don’t poll it.
Errors
- An unknown contract ID, or a contract that belongs to another store, returns
400with theerrorKeyinvalidContract. - A contract ID that isn’t a number returns
400withUnexpected runtime exception. - When Shopify throttles the read twice in a row, the call returns
400with atitlethat containsShopify GraphQL API request was throttled. Wait a few seconds, then retry. - An ID that Appstle has but Shopify no longer returns gets
404. - A missing or invalid API key returns
401. - Too many calls for the store return
429with aRetry-Afterheader. Wait that many seconds before you retry.
Authentication: Requires a valid X-API-Key header. A Read only key works.
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"__typename": "SubscriptionContract",
"billingAttempts": {
"__typename": "SubscriptionBillingAttemptConnection",
"nodes": []
},
"billingPolicy": {
"__typename": "SubscriptionBillingPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1,
"maxCycles": null,
"minCycles": null
},
"createdAt": "2026-10-26T02:51:57Z",
"customAttributes": [],
"customer": {
"__typename": "Customer",
"displayName": "Jane Smith",
"email": "jane.smith@example.com",
"firstName": "Jane",
"id": "gid://shopify/Customer/6660000000001",
"lastName": "Smith",
"phone": null
},
"customerPaymentMethod": {
"__typename": "CustomerPaymentMethod",
"id": "gid://shopify/CustomerPaymentMethod/0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"instrument": {
"__typename": "CustomerCreditCard",
"billingAddress": {
"__typename": "CustomerCreditCardBillingAddress",
"address1": "123 Main St",
"city": "San Francisco",
"country": "United States",
"countryCode": "US",
"firstName": "Jane",
"lastName": "Smith",
"province": "California",
"provinceCode": "CA",
"zip": "94105"
},
"brand": "visa",
"expiresSoon": false,
"expiryMonth": 12,
"expiryYear": 2030,
"firstDigits": "424242",
"lastDigits": "4242",
"maskedNumber": "•••• •••• •••• 4242",
"name": "Jane Smith",
"revocable": false,
"source": "credit_card"
},
"revokedAt": null,
"revokedReason": null
},
"deliveryMethod": {
"__typename": "SubscriptionDeliveryMethodShipping",
"address": {
"__typename": "MailingAddress",
"address1": "123 Main St",
"address2": null,
"city": "San Francisco",
"company": null,
"country": "United States",
"countryCode": "US",
"countryCodeV2": "US",
"firstName": "Jane",
"lastName": "Smith",
"name": "Jane Smith",
"phone": null,
"province": "California",
"provinceCode": "CA",
"zip": "94105"
},
"shippingOption": {
"__typename": "SubscriptionDeliveryMethodShippingOption",
"code": "Standard",
"description": null,
"presentmentTitle": "Standard",
"title": "Standard"
}
},
"deliveryPolicy": {
"__typename": "SubscriptionDeliveryPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1
},
"deliveryPrice": {
"__typename": "MoneyV2",
"amount": "5.0",
"currencyCode": "USD"
},
"discounts": {
"__typename": "SubscriptionManualDiscountConnection",
"nodes": [],
"pageInfo": {
"__typename": "PageInfo",
"endCursor": "eyJsYXN0X2lkIjoxfQ",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJsYXN0X2lkIjoxfQ"
}
},
"id": "gid://shopify/SubscriptionContract/5001234567",
"lastPaymentStatus": null,
"lines": {
"__typename": "SubscriptionLineConnection",
"nodes": [
{
"__typename": "SubscriptionLine",
"currentPrice": {
"__typename": "MoneyV2",
"amount": "16.2",
"currencyCode": "USD"
},
"customAttributes": [
{
"__typename": "Attribute",
"key": "Gift message",
"value": "Happy birthday"
}
],
"discountAllocations": [],
"id": "gid://shopify/SubscriptionLine/2f8c1d4e-7a3b-4c19-9d5e-6b0a1c2d3e4f",
"lineDiscountedPrice": {
"__typename": "MoneyV2",
"amount": "16.2",
"currencyCode": "USD"
},
"pricingPolicy": {
"__typename": "SubscriptionPricingPolicy",
"basePrice": {
"__typename": "MoneyV2",
"amount": "18.0",
"currencyCode": "USD"
},
"cycleDiscounts": [
{
"__typename": "SubscriptionCyclePriceAdjustment",
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"__typename": "SellingPlanPricingPolicyPercentageValue",
"percentage": 10
},
"afterCycle": 0,
"computedPrice": {
"__typename": "MoneyV2",
"amount": "16.2",
"currencyCode": "USD"
}
}
]
},
"productId": "gid://shopify/Product/7001000000001",
"quantity": 1,
"sellingPlanId": "gid://shopify/SellingPlan/690000000001",
"sellingPlanName": "Monthly Subscription",
"sku": null,
"taxable": true,
"title": "House Blend Coffee",
"variantId": "gid://shopify/ProductVariant/44190100000001",
"variantTitle": null
}
],
"pageInfo": {
"__typename": "PageInfo",
"endCursor": "eyJsYXN0X2lkIjoxfQ",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJsYXN0X2lkIjoxfQ"
}
},
"nextBillingDate": "2026-11-26T03:00:00Z",
"note": null,
"originOrder": {
"__typename": "Order",
"fulfillmentOrders": {
"__typename": "FulfillmentOrderConnection",
"nodes": [],
"pageInfo": {
"__typename": "PageInfo",
"endCursor": "eyJsYXN0X2lkIjoxfQ",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJsYXN0X2lkIjoxfQ"
}
},
"id": "gid://shopify/Order/5550000000001",
"name": "#1001"
},
"revisionId": "600059347248",
"status": "ACTIVE",
"updatedAt": "2026-11-09T03:01:18Z"
}Response
Successfully retrieved the contract from Shopify
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"__typename": "SubscriptionContract",
"billingAttempts": {
"__typename": "SubscriptionBillingAttemptConnection",
"nodes": []
},
"billingPolicy": {
"__typename": "SubscriptionBillingPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1,
"maxCycles": null,
"minCycles": null
},
"createdAt": "2026-10-26T02:51:57Z",
"customAttributes": [],
"customer": {
"__typename": "Customer",
"displayName": "Jane Smith",
"email": "jane.smith@example.com",
"firstName": "Jane",
"id": "gid://shopify/Customer/6660000000001",
"lastName": "Smith",
"phone": null
},
"customerPaymentMethod": {
"__typename": "CustomerPaymentMethod",
"id": "gid://shopify/CustomerPaymentMethod/0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"instrument": {
"__typename": "CustomerCreditCard",
"billingAddress": {
"__typename": "CustomerCreditCardBillingAddress",
"address1": "123 Main St",
"city": "San Francisco",
"country": "United States",
"countryCode": "US",
"firstName": "Jane",
"lastName": "Smith",
"province": "California",
"provinceCode": "CA",
"zip": "94105"
},
"brand": "visa",
"expiresSoon": false,
"expiryMonth": 12,
"expiryYear": 2030,
"firstDigits": "424242",
"lastDigits": "4242",
"maskedNumber": "•••• •••• •••• 4242",
"name": "Jane Smith",
"revocable": false,
"source": "credit_card"
},
"revokedAt": null,
"revokedReason": null
},
"deliveryMethod": {
"__typename": "SubscriptionDeliveryMethodShipping",
"address": {
"__typename": "MailingAddress",
"address1": "123 Main St",
"address2": null,
"city": "San Francisco",
"company": null,
"country": "United States",
"countryCode": "US",
"countryCodeV2": "US",
"firstName": "Jane",
"lastName": "Smith",
"name": "Jane Smith",
"phone": null,
"province": "California",
"provinceCode": "CA",
"zip": "94105"
},
"shippingOption": {
"__typename": "SubscriptionDeliveryMethodShippingOption",
"code": "Standard",
"description": null,
"presentmentTitle": "Standard",
"title": "Standard"
}
},
"deliveryPolicy": {
"__typename": "SubscriptionDeliveryPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1
},
"deliveryPrice": {
"__typename": "MoneyV2",
"amount": "5.0",
"currencyCode": "USD"
},
"discounts": {
"__typename": "SubscriptionManualDiscountConnection",
"nodes": [],
"pageInfo": {
"__typename": "PageInfo",
"endCursor": "eyJsYXN0X2lkIjoxfQ",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJsYXN0X2lkIjoxfQ"
}
},
"id": "gid://shopify/SubscriptionContract/5001234567",
"lastPaymentStatus": null,
"lines": {
"__typename": "SubscriptionLineConnection",
"nodes": [
{
"__typename": "SubscriptionLine",
"currentPrice": {
"__typename": "MoneyV2",
"amount": "16.2",
"currencyCode": "USD"
},
"customAttributes": [
{
"__typename": "Attribute",
"key": "Gift message",
"value": "Happy birthday"
}
],
"discountAllocations": [],
"id": "gid://shopify/SubscriptionLine/2f8c1d4e-7a3b-4c19-9d5e-6b0a1c2d3e4f",
"lineDiscountedPrice": {
"__typename": "MoneyV2",
"amount": "16.2",
"currencyCode": "USD"
},
"pricingPolicy": {
"__typename": "SubscriptionPricingPolicy",
"basePrice": {
"__typename": "MoneyV2",
"amount": "18.0",
"currencyCode": "USD"
},
"cycleDiscounts": [
{
"__typename": "SubscriptionCyclePriceAdjustment",
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"__typename": "SellingPlanPricingPolicyPercentageValue",
"percentage": 10
},
"afterCycle": 0,
"computedPrice": {
"__typename": "MoneyV2",
"amount": "16.2",
"currencyCode": "USD"
}
}
]
},
"productId": "gid://shopify/Product/7001000000001",
"quantity": 1,
"sellingPlanId": "gid://shopify/SellingPlan/690000000001",
"sellingPlanName": "Monthly Subscription",
"sku": null,
"taxable": true,
"title": "House Blend Coffee",
"variantId": "gid://shopify/ProductVariant/44190100000001",
"variantTitle": null
}
],
"pageInfo": {
"__typename": "PageInfo",
"endCursor": "eyJsYXN0X2lkIjoxfQ",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJsYXN0X2lkIjoxfQ"
}
},
"nextBillingDate": "2026-11-26T03:00:00Z",
"note": null,
"originOrder": {
"__typename": "Order",
"fulfillmentOrders": {
"__typename": "FulfillmentOrderConnection",
"nodes": [],
"pageInfo": {
"__typename": "PageInfo",
"endCursor": "eyJsYXN0X2lkIjoxfQ",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJsYXN0X2lkIjoxfQ"
}
},
"id": "gid://shopify/Order/5550000000001",
"name": "#1001"
},
"revisionId": "600059347248",
"status": "ACTIVE",
"updatedAt": "2026-11-09T03:01:18Z"
}