External APIs (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Creates a new subscription contract for a customer with specified products, billing frequency, and delivery details. This endpoint allows you to programmatically create subscriptions with custom pricing, delivery schedules, and multiple line items. The subscription will be created in Shopify and synchronized with the Appstle system.

Important Notes:

• Customer must have at least one valid payment method
• If paymentMethodId is not provided, the default payment method will be used
• If delivery interval is not specified, it defaults to the billing interval
• Custom pricing policies can be applied per line item
• All monetary values are in the store's base currency unless currencyCode is specified
• CustomAttributes and line item customAttributes use Shopify's AttributeInput format: {"key": "string", "value": "string"}

Pricing Policy Types:

• SELLING_PLAN_PRICING_POLICY: Uses the default pricing from the selling plan
• CUSTOM_PRICING_POLICY: Allows custom discount cycles defined in pricingPolicy array
• NO_PRICING_POLICY: Uses the base price without any discounts

Authentication: Requires valid X-API-Key header

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:

1. Use for Debugging: Perfect for troubleshooting data issues
2. Avoid Polling: Don't call repeatedly - use cached/processed endpoints instead
3. Cache Response: Cache the response if using for display
4. Parse Carefully: Handle GraphQL structure (edges/nodes)
5. 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

Retrieves fulfillment information for the most recent successful order associated with a subscription contract. This includes tracking details, shipment status, delivery estimates, and fulfillment line items from Shopify.

What This Endpoint Returns: Complete fulfillment data for the subscription's last successfully billed order, queried in real-time from Shopify's GraphQL API. Shows customers when and how their subscription items will be (or were) delivered.

Fulfillment Data Included:

Shipment Tracking:

• Tracking numbers and URLs
• Carrier information (USPS, FedEx, UPS, etc.)
• Tracking company details
• Tracking status updates

Delivery Status:

• Fulfillment status (fulfilled, in_transit, out_for_delivery, delivered, etc.)
• Estimated delivery date
• Actual delivery timestamp (if delivered)
• Delivery method (shipping, pickup, local delivery)

Fulfillment Details:

• Fulfilled line items (which products shipped)
• Quantities fulfilled
• Fulfillment service (manual, automated, 3PL)
• Fulfillment created/updated dates
• Multiple fulfillments (if order shipped in parts)

Location Information:

• Fulfillment location/warehouse
• Origin address details
• Fulfillment service name

Order Determination Logic:

Which Order is Retrieved:

1. Finds most recent SUCCESS billing attempt for contract
2. If found: Uses that order's Shopify order ID
3. If none: Falls back to subscription's origin order ID
4. Queries Shopify for that order's fulfillments

Why This Matters:

• Shows CURRENT/LATEST fulfillment status
• Not historical fulfillments from months ago
• Reflects what customer is waiting for NOW
• Updates after each new billing cycle

Use Cases:

1. Customer Portal "Where's My Order":

• Display tracking information
• Show estimated delivery date
• Provide carrier tracking links
• Update fulfillment status

2. Subscription Order Tracking:

• Track recurring order deliveries
• Monitor fulfillment progress
• Identify delayed shipments
• Provide proactive delivery updates

3. Customer Support:

• Answer "where is my order" questions
• Verify shipment details
• Troubleshoot delivery issues
• Provide accurate tracking info

4. Automated Notifications:

• Send tracking emails automatically
• Notify customers of shipments
• Alert on delivery completion
• Trigger review request flows

5. Subscription Management:

• Show fulfillment in subscription history
• Display delivery patterns
• Track fulfillment reliability
• Monitor shipping performance

Response Structure:

Returns Shopify Order object with fulfillments:

{
  "id": "gid://shopify/Order/123456789",
  "name": "#1001",
  "fulfillmentOrders": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/FulfillmentOrder/111111",
          "status": "SUCCESS",
          "fulfillments": {
            "edges": [
              {
                "node": {
                  "trackingInfo": [
                    {
                      "number": "1Z999AA10123456784",
                      "url": "https://wwwapps.ups.com/tracking/...",
                      "company": "UPS"
                    }
                  ],
                  "status": "IN_TRANSIT",
                  "estimatedDeliveryAt": "2024-03-20T00:00:00Z",
                  "deliveredAt": null
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Common Scenarios:

Scenario: Order Fulfilled & Shipped

{
  "trackingInfo": [{"number": "9400...", "company": "USPS"}],
  "status": "IN_TRANSIT",
  "estimatedDeliveryAt": "2024-03-18T00:00:00Z"
}

Scenario: Order Delivered

{
  "status": "DELIVERED",
  "deliveredAt": "2024-03-15T14:23:00Z"
}

Scenario: Not Yet Fulfilled

{
  "fulfillmentOrders": {
    "edges": [
      {
        "node": {
          "status": "OPEN",
          "fulfillments": {"edges": []}
        }
      }
    ]
  }
}

Scenario: No Order Yet (New Subscription) Returns null or empty response

Important Considerations:

Real-Time Shopify Query:

• Makes live call to Shopify GraphQL API
• NOT cached data
• Response time: 500-1500ms
• Subject to Shopify rate limits

Data Freshness:

• Returns current fulfillment status from Shopify
• Tracking updates reflect Shopify's data
• May lag behind carrier's actual status
• Shopify updates tracking periodically

Null Responses:

• Returns null if no orders exist yet
• Returns null if order ID not found
• Handle gracefully in UI

Multiple Fulfillments:

• Order may have multiple fulfillments (split shipments)
• Each fulfillment has own tracking
• Iterate through all fulfillment nodes

Integration Example:

Customer Portal - Track Shipment:

const order = await fetch(
  `/api/external/v2/subscription-contract-details/subscription-fulfillments/${contractId}`,
  { headers: { 'X-API-Key': 'your-key' } }
).then(r => r.json());

if (!order) {
  return '<p>No shipment information available yet.</p>';
}

const fulfillments = order.fulfillmentOrders?.edges || [];
fulfillments.forEach(fo => {
  fo.node.fulfillments?.edges?.forEach(f => {
    const tracking = f.node.trackingInfo?.[0];
    if (tracking) {
      console.log(`Track with ${tracking.company}: ${tracking.number}`);
      console.log(`URL: ${tracking.url}`);
    }
  });
});

Best Practices:

1. Cache Response: Cache for 30-60 minutes to reduce Shopify API calls
2. Handle Nulls: Always check for null/empty responses
3. Parse GraphQL: Navigate edges/nodes structure carefully
4. Show All Tracking: Display all fulfillments if multiple shipments
5. Link to Carrier: Provide clickable tracking URLs

Authentication: Requires valid X-API-Key header