Subscription Management

Get raw Shopify GraphQL contract response

Retrieves the complete, unprocessed subscription contract data directly from Shopify’s GraphQL API. This endpoint returns the full Shopify subscription contract object exactly as Shopify provides it, including all nested fields, relationships, and GraphQL metadata.

What This Endpoint Returns: Unlike processed/transformed endpoints, this returns Shopify’s raw SubscriptionContract GraphQL object with all available fields. This is the same data structure you would receive if querying Shopify’s GraphQL API directly, making it ideal for:

Debugging Shopify data synchronization issues
Accessing fields not exposed in other endpoints
Understanding complete Shopify contract structure
Building custom integrations requiring full data
Comparing Shopify source data with processed data

Data Included:

Contract Core:

Full subscription contract object from Shopify
All GraphQL __typename fields preserved
Complete nested object structures
All available Shopify contract fields

Customer Information:

Complete customer object with all fields
Default address details
Customer tags and metadata
Marketing preferences

Line Items:

Full line item details with edges/nodes structure
Product and variant complete objects
Pricing policies with all cycle discounts
Line item custom attributes
Current and original prices

Billing & Delivery:

Complete billing policy object
Full delivery policy details
Delivery method with all fields
Delivery price breakdown
Billing anchor details

Payment Information:

Payment method details (if available)
Customer payment instrument
Payment gateway information

Orders & History:

Origin order details
Last payment status
Historical billing attempts (in Appstle)

Use Cases:

1. Debugging & Troubleshooting:

Investigate data sync discrepancies
Verify what Shopify actually stores
Debug webhook payload issues
Compare expected vs actual data

2. Advanced Integrations:

Access Shopify-specific fields not in standard APIs
Build custom analytics using raw data
Integrate with Shopify GraphQL directly
Extract fields for custom processing

3. Data Analysis:

Analyze complete contract structure
Extract all available metadata
Build comprehensive data exports
Perform deep data audits

4. Development & Testing:

Understand Shopify’s data model
Test new feature development
Verify API responses
Documentation and examples

Response Structure:

Returns SubscriptionContractQuery.SubscriptionContract object:

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-15T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "displayName": "John Doe",
    "__typename": "Customer"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/222222",
          "title": "Monthly Coffee Box",
          "variantTitle": "Medium Roast",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "pricingPolicy": {...},
          "__typename": "SubscriptionLine"
        }
      }
    ]
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "minCycles": 3,
    "maxCycles": 12
  },
  "deliveryPolicy": {...},
  "deliveryMethod": {...},
  "__typename": "SubscriptionContract"
}

Important Considerations:

Data Source:

Queries Shopify GraphQL API in real-time
NOT cached in Appstle database
Always returns current Shopify state
Subject to Shopify API rate limits

Performance:

Slower than database queries (500-1500ms typical)
Makes real-time call to Shopify
Response size can be large (10-50 KB)
Use sparingly to avoid rate limits

GraphQL Structure:

Includes __typename fields throughout
Uses GraphQL ID format (gid://shopify/…)
Nested edges/nodes structure for lists
All fields as defined in Shopify’s schema

Best Practices:

Use for Debugging: Perfect for troubleshooting data issues
Avoid Polling: Don’t call repeatedly - use cached/processed endpoints instead
Cache Response: Cache the response if using for display
Parse Carefully: Handle GraphQL structure (edges/nodes)
Monitor Rate Limits: Each call counts against Shopify API limits

When to Use vs Other Endpoints:

Use this endpoint when:

Need complete Shopify contract data
Debugging synchronization issues
Accessing Shopify-specific fields
Building Shopify GraphQL integrations

Use /api/external/v2/subscription-contract-details when:

Need processed, filtered contract data
Want faster response times
Querying multiple contracts
Building customer-facing UIs

Authentication: Requires valid X-API-Key header

GET

api

external

subscription-contracts

contract-external

{contractId}

Get raw Shopify GraphQL contract response

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}

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

{
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "completedAt": {},
        "createdAt": {},
        "get__typename": "<string>",
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  },
  "billingPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123,
        "type": "WEEKDAY"
      }
    ],
    "get__typename": "<string>",
    "interval": "DAY",
    "intervalCount": 123,
    "maxCycles": 123,
    "minCycles": 123
  },
  "createdAt": {},
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "customer": {
    "displayName": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "get__typename": "<string>",
    "id": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "<string>"
  },
  "deliveryPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123,
        "type": "WEEKDAY"
      }
    ],
    "get__typename": "<string>",
    "interval": "DAY",
    "intervalCount": 123
  },
  "deliveryPrice": {
    "amount": {},
    "currencyCode": "USD",
    "get__typename": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "id": "<string>",
        "recurringCycleLimit": 123,
        "rejectionReason": "NOT_FOUND",
        "targetType": "LINE_ITEM",
        "title": "<string>",
        "type": "MANUAL",
        "usageCount": 123,
        "value": {
          "get__typename": "<string>"
        }
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "get__typename": "<string>",
  "id": "<string>",
  "lastPaymentStatus": "SUCCEEDED",
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "currentPrice": {
          "amount": {},
          "currencyCode": "USD",
          "get__typename": "<string>"
        },
        "customAttributes": [
          {
            "get__typename": "<string>",
            "key": "<string>",
            "value": "<string>"
          }
        ],
        "discountAllocations": [
          {
            "amount": {
              "amount": {},
              "currencyCode": "USD",
              "get__typename": "<string>"
            },
            "discount": {
              "get__typename": "<string>"
            },
            "get__typename": "<string>"
          }
        ],
        "get__typename": "<string>",
        "id": "<string>",
        "lineDiscountedPrice": {
          "amount": {},
          "currencyCode": "USD",
          "get__typename": "<string>"
        },
        "pricingPolicy": {
          "basePrice": {
            "amount": {},
            "currencyCode": "USD",
            "get__typename": "<string>"
          },
          "cycleDiscounts": [
            {
              "adjustmentType": "PERCENTAGE",
              "adjustmentValue": {
                "get__typename": "<string>"
              },
              "afterCycle": 123,
              "computedPrice": {
                "amount": {},
                "currencyCode": "USD",
                "get__typename": "<string>"
              },
              "get__typename": "<string>"
            }
          ],
          "get__typename": "<string>"
        },
        "productId": "<string>",
        "quantity": 123,
        "sellingPlanId": "<string>",
        "sellingPlanName": "<string>",
        "sku": "<string>",
        "taxable": true,
        "title": "<string>",
        "variantId": "<string>",
        "variantImage": {
          "get__typename": "<string>",
          "url": {}
        },
        "variantTitle": "<string>"
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "nextBillingDate": {},
  "note": "<string>",
  "originOrder": {
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "fulfillAt": {},
          "get__typename": "<string>",
          "id": "<string>",
          "status": "OPEN"
        }
      ],
      "pageInfo": {
        "endCursor": "<string>",
        "get__typename": "<string>",
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "<string>"
      }
    },
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>"
  },
  "status": "ACTIVE",
  "updatedAt": {}
}

{
  "detail": "Contract ID must be a valid positive integer",
  "status": 400,
  "title": "Invalid contract ID",
  "type": "https://example.com/errors/bad-request"
}

{
  "detail": "Valid X-API-Key header is required",
  "status": 401,
  "title": "Authentication required",
  "type": "https://example.com/errors/unauthorized"
}

{
  "detail": "Subscription contract does not belong to your shop",
  "status": 403,
  "title": "Access denied",
  "type": "https://example.com/errors/forbidden"
}

{
  "detail": "No subscription contract found with ID 12345 in Shopify",
  "status": 404,
  "title": "Contract not found",
  "type": "https://example.com/errors/not-found"
}

{
  "detail": "Shopify API rate limit exceeded. Please retry after 60 seconds.",
  "retryAfter": 60,
  "status": 429,
  "title": "Rate limit exceeded",
  "type": "https://example.com/errors/rate-limit"
}

{
  "detail": "Failed to retrieve contract from Shopify. Please try again later.",
  "status": 502,
  "title": "Shopify API error",
  "type": "https://example.com/errors/bad-gateway"
}

Headers

X-API-Key

string

Path Parameters

contractId

integer<int64>

required

Contract ID

Query Parameters

api_key

string

API Key (Deprecated - Use Header X-API-Key instead)

Response

Successfully retrieved raw Shopify contract data

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

Get raw Shopify GraphQL contract response

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/contract-external/{contractId}

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

{
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "completedAt": {},
        "createdAt": {},
        "get__typename": "<string>",
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  },
  "billingPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123,
        "type": "WEEKDAY"
      }
    ],
    "get__typename": "<string>",
    "interval": "DAY",
    "intervalCount": 123,
    "maxCycles": 123,
    "minCycles": 123
  },
  "createdAt": {},
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "customer": {
    "displayName": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "get__typename": "<string>",
    "id": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "<string>"
  },
  "deliveryPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123,
        "type": "WEEKDAY"
      }
    ],
    "get__typename": "<string>",
    "interval": "DAY",
    "intervalCount": 123
  },
  "deliveryPrice": {
    "amount": {},
    "currencyCode": "USD",
    "get__typename": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "id": "<string>",
        "recurringCycleLimit": 123,
        "rejectionReason": "NOT_FOUND",
        "targetType": "LINE_ITEM",
        "title": "<string>",
        "type": "MANUAL",
        "usageCount": 123,
        "value": {
          "get__typename": "<string>"
        }
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "get__typename": "<string>",
  "id": "<string>",
  "lastPaymentStatus": "SUCCEEDED",
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "currentPrice": {
          "amount": {},
          "currencyCode": "USD",
          "get__typename": "<string>"
        },
        "customAttributes": [
          {
            "get__typename": "<string>",
            "key": "<string>",
            "value": "<string>"
          }
        ],
        "discountAllocations": [
          {
            "amount": {
              "amount": {},
              "currencyCode": "USD",
              "get__typename": "<string>"
            },
            "discount": {
              "get__typename": "<string>"
            },
            "get__typename": "<string>"
          }
        ],
        "get__typename": "<string>",
        "id": "<string>",
        "lineDiscountedPrice": {
          "amount": {},
          "currencyCode": "USD",
          "get__typename": "<string>"
        },
        "pricingPolicy": {
          "basePrice": {
            "amount": {},
            "currencyCode": "USD",
            "get__typename": "<string>"
          },
          "cycleDiscounts": [
            {
              "adjustmentType": "PERCENTAGE",
              "adjustmentValue": {
                "get__typename": "<string>"
              },
              "afterCycle": 123,
              "computedPrice": {
                "amount": {},
                "currencyCode": "USD",
                "get__typename": "<string>"
              },
              "get__typename": "<string>"
            }
          ],
          "get__typename": "<string>"
        },
        "productId": "<string>",
        "quantity": 123,
        "sellingPlanId": "<string>",
        "sellingPlanName": "<string>",
        "sku": "<string>",
        "taxable": true,
        "title": "<string>",
        "variantId": "<string>",
        "variantImage": {
          "get__typename": "<string>",
          "url": {}
        },
        "variantTitle": "<string>"
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "nextBillingDate": {},
  "note": "<string>",
  "originOrder": {
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "fulfillAt": {},
          "get__typename": "<string>",
          "id": "<string>",
          "status": "OPEN"
        }
      ],
      "pageInfo": {
        "endCursor": "<string>",
        "get__typename": "<string>",
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "<string>"
      }
    },
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>"
  },
  "status": "ACTIVE",
  "updatedAt": {}
}

{
  "detail": "Contract ID must be a valid positive integer",
  "status": 400,
  "title": "Invalid contract ID",
  "type": "https://example.com/errors/bad-request"
}

{
  "detail": "Valid X-API-Key header is required",
  "status": 401,
  "title": "Authentication required",
  "type": "https://example.com/errors/unauthorized"
}

{
  "detail": "Subscription contract does not belong to your shop",
  "status": 403,
  "title": "Access denied",
  "type": "https://example.com/errors/forbidden"
}

{
  "detail": "No subscription contract found with ID 12345 in Shopify",
  "status": 404,
  "title": "Contract not found",
  "type": "https://example.com/errors/not-found"
}

{
  "detail": "Shopify API rate limit exceeded. Please retry after 60 seconds.",
  "retryAfter": 60,
  "status": 429,
  "title": "Rate limit exceeded",
  "type": "https://example.com/errors/rate-limit"
}

{
  "detail": "Failed to retrieve contract from Shopify. Please try again later.",
  "status": 502,
  "title": "Shopify API error",
  "type": "https://example.com/errors/bad-gateway"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Get raw Shopify GraphQL contract response

Headers

Path Parameters

Query Parameters

Response