Get customer details with subscriptions

Retrieves comprehensive customer information including their subscription contracts. This endpoint provides customer profile data along with a paginated list of their active and historical subscriptions.

Full behavior, validation rules, and side effects

Key Features:

• Customer profile information (name, email, phone, addresses)
• Complete subscription history with pagination
• Payment method details
• Customer account state and metadata
• Order history related to subscriptions
• Customer tags and notes

Subscription Data Included:

• All subscription contracts (active, paused, cancelled)
• Contract details with line items
• Billing and delivery policies
• Next billing dates and amounts
• Applied discounts

Pagination:

• Subscription contracts are paginated
• Default page size varies by Shopify plan
• Use cursor for subsequent pages
• Cursor-based pagination ensures consistency

Use Cases:

• Customer service representatives viewing customer details
• Integration with CRM systems
• Customer analytics and reporting
• Subscription management interfaces
• Billing reconciliation

Important Notes:

• Customer ID is numeric (without gid:// prefix)
• Returns null if customer not found
• Includes both active and inactive subscriptions
• Payment methods may be masked for security

Authentication: Requires valid X-API-Key header

GET /api/external/v2/subscription-customers/{id}

Get customer details with subscriptions

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-customers/{id} \
  --header 'X-API-Key: <x-api-key>'

200

Success Response

{
  "id": "gid://shopify/Customer/987654321",
  "displayName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "phone": "[phone]",
  "state": "ENABLED",
  "acceptsMarketing": true,
  "createdAt": "2023-01-15T10:30:00Z",
  "updatedAt": "2024-03-15T14:45:00Z",
  "tags": [
    "VIP",
    "Subscription"
  ],
  "note": "Preferred customer - handle with care",
  "verifiedEmail": true,
  "validEmailAddress": true,
  "defaultAddress": {
    "id": "gid://shopify/MailingAddress/123456789",
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "New York",
    "province": "New York",
    "provinceCode": "NY",
    "country": "United States",
    "countryCode": "US",
    "zip": "10001",
    "phone": "[phone]",
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Corp"
  },
  "addresses": [
    {
      "id": "gid://shopify/MailingAddress/123456789",
      "address1": "123 Main St",
      "city": "New York",
      "provinceCode": "NY",
      "countryCode": "US",
      "zip": "10001"
    },
    {
      "id": "gid://shopify/MailingAddress/987654321",
      "address1": "456 Office Blvd",
      "city": "Brooklyn",
      "provinceCode": "NY",
      "countryCode": "US",
      "zip": "11201"
    }
  ],
  "paymentMethods": [
    {
      "id": "gid://shopify/CustomerPaymentMethod/111111",
      "instrument": {
        "__typename": "CustomerCreditCard",
        "brand": "VISA",
        "lastDigits": "4242",
        "expiryMonth": 12,
        "expiryYear": 2025,
        "maskedNumber": "•••• •••• •••• 4242"
      }
    }
  ],
  "subscriptionContracts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionContract/123456789",
          "status": "ACTIVE",
          "nextBillingDate": "2024-04-01T12:00:00Z",
          "createdAt": "2024-01-15T10:00:00Z",
          "updatedAt": "2024-03-15T14:30:00Z",
          "billingPolicy": {
            "interval": "MONTH",
            "intervalCount": 1
          },
          "deliveryPolicy": {
            "interval": "MONTH",
            "intervalCount": 1
          },
          "lines": {
            "edges": [
              {
                "node": {
                  "id": "gid://shopify/SubscriptionLine/111111",
                  "productId": "gid://shopify/Product/7890123456",
                  "variantId": "gid://shopify/ProductVariant/42549172011164",
                  "title": "Premium Coffee Subscription",
                  "quantity": 2,
                  "currentPrice": {
                    "amount": "59.98",
                    "currencyCode": "USD"
                  }
                }
              }
            ]
          }
        },
        "cursor": "eyJsYXN0X2lkIjoxMjM0NTY3ODksImxhc3RfdmFsdWUiOiIyMDI0LTAxLTE1IDEwOjAwOjAwIn0="
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJsYXN0X2lkIjoxMjM0NTY3ODksImxhc3RfdmFsdWUiOiIyMDI0LTAxLTE1IDEwOjAwOjAwIn0=",
      "endCursor": "eyJsYXN0X2lkIjoxMjM0NTY3OTAsImxhc3RfdmFsdWUiOiIyMDI0LTAyLTAxIDEyOjAwOjAwIn0="
    }
  },
  "numberOfOrders": "15"
}

Headers

X-API-Key · string · required

API Key for authentication

Path Parameters

id · integer<int64> · required

Customer ID to retrieve. Provide the numeric ID without the gid:// prefix

Required range: x >= 1

Query Parameters

api_key · string

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

cursor · string

Pagination cursor for subscription contracts. Use the cursor from previous response's pageInfo.endCursor to get the next page

Response

200

application/json

Customer details successfully retrieved

get__typename · string

id · string

email · string · deprecated

displayName · string

firstName · string

lastName · string

phone · string · deprecated