> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get subscription fulfillment details for latest order

> 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:
```json
{
  "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**
```json
{
  "trackingInfo": [{"number": "9400...", "company": "USPS"}],
  "status": "IN_TRANSIT",
  "estimatedDeliveryAt": "2024-03-18T00:00:00Z"
}
```

**Scenario: Order Delivered**
```json
{
  "status": "DELIVERED",
  "deliveredAt": "2024-03-15T14:23:00Z"
}
```

**Scenario: Not Yet Fulfilled**
```json
{
  "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:**
```javascript
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



## OpenAPI

````yaml /subscription/admin-api-swagger.json get /api/external/v2/subscription-contract-details/subscription-fulfillments/{contractId}
openapi: 3.0.1
info:
  description: >-
    Comprehensive API documentation for managing subscriptions, payments, and
    related operations. These APIs allow you to programmatically manage
    subscription lifecycles, handle payments, configure products, and integrate
    subscription functionality into your applications.
  title: Admin APIs
  version: 0.0.1
servers:
  - url: https://subscription-admin.appstle.com
security: []
tags:
  - description: >-
      Core APIs for managing the complete subscription lifecycle including
      creation, updates, pausing, resuming, and cancellation of subscriptions.
    name: Subscription Management
  - description: >-
      APIs for managing subscription payment methods, processing payments,
      handling payment retries, and updating billing information.
    name: Subscription Payments
  - description: >-
      APIs for managing subscription contracts including delivery schedules,
      pricing, order notes, billing cycles, and shipping addresses.
    name: Subscription Contracts
  - description: >-
      APIs for managing products within subscriptions including adding,
      removing, updating quantities, and swapping products.
    name: Subscription Products
  - description: >-
      APIs for handling billing operations, payment processing, and financial
      transactions related to subscriptions.
    name: Billing & Payments
  - description: >-
      APIs for managing discounts and promotional codes applied to
      subscriptions.
    name: Subscription Discounts
  - description: >-
      APIs for managing one-time add-on products that can be purchased alongside
      recurring subscription items.
    name: Subscription One-Time Products
  - description: >-
      APIs for managing subscription plans, pricing tiers, and plan
      configurations.
    name: Subscription Plans
  - description: >-
      APIs for managing customizable product boxes and bundles where customers
      can select multiple items.
    name: Build-a-Box & Bundles
  - description: >-
      APIs for managing the product catalog including product information,
      variants, and inventory.
    name: Product Catalog
  - description: >-
      APIs for managing operational settings, configurations, and administrative
      functions.
    name: Operations & Settings
  - description: >-
      APIs powering the customer-facing portal where subscribers can manage
      their own subscriptions.
    name: Customer Portal
  - description: APIs for managing customer information, profiles, and account details.
    name: Customers
  - description: >-
      APIs for retrieving aggregated subscription data, customer subscription
      history, and account-level subscription information.
    name: Subscription Data
  - description: >-
      APIs for managing delivery profiles, shipping rates, free shipping
      configuration, and delivery method options on subscriptions.
    name: Delivery & Shipping
  - description: >-
      APIs for managing storefront customization including custom CSS, theme
      settings, label translations, and merchant-defined widget configuration.
    name: Customization
  - description: >-
      APIs for configuring cancellation flows, retention offers, cancellation
      reason management, and win-back automation.
    name: Customer Retention
paths:
  /api/external/v2/subscription-contract-details/subscription-fulfillments/{contractId}:
    get:
      tags:
        - Subscription Management
        - Subscription Contracts
      summary: Get subscription fulfillment details for latest order
      description: >-
        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:

        ```json

        {
          "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**

        ```json

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

        ```


        **Scenario: Order Delivered**

        ```json

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

        ```


        **Scenario: Not Yet Fulfilled**

        ```json

        {
          "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:**

        ```javascript

        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
      operationId: getSubscriptionFulfillmentsExternalV2
      parameters:
        - description: Contract ID
          in: path
          name: contractId
          required: true
          schema:
            format: int64
            type: integer
        - description: API Key (Deprecated - Use Header X-API-Key instead)
          in: query
          name: api_key
          required: false
          schema:
            type: string
        - in: header
          name: X-API-Key
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
          description: >-
            Successfully retrieved fulfillment details (may be null if no orders
            exist)
        '400':
          content:
            application/json:
              example:
                detail: Contract ID must be a valid positive integer
                status: 400
                title: Invalid contract ID
                type: https://example.com/errors/bad-request
          description: Bad request - Invalid contract ID
        '401':
          content:
            application/json:
              example:
                detail: Valid X-API-Key header is required
                status: 401
                title: Authentication required
                type: https://example.com/errors/unauthorized
          description: Authentication required
        '403':
          content:
            application/json:
              example:
                detail: Contract does not belong to your shop
                status: 403
                title: Access denied
                type: https://example.com/errors/forbidden
          description: Forbidden - Contract does not belong to authenticated shop
        '502':
          content:
            application/json:
              example:
                detail: Failed to retrieve fulfillment data from Shopify
                status: 502
                title: Shopify API error
                type: https://example.com/errors/bad-gateway
          description: Bad gateway - Shopify API error
components:
  schemas:
    Order:
      properties:
        fulfillmentOrders:
          $ref: '#/components/schemas/FulfillmentOrders'
        get__typename:
          type: string
        id:
          type: string
      type: object
    FulfillmentOrders:
      properties:
        get__typename:
          type: string
        nodes:
          items:
            $ref: '#/components/schemas/Node1'
          type: array
        pageInfo:
          $ref: '#/components/schemas/PageInfo1'
      type: object
    Node1:
      properties:
        fulfillAt:
          type: object
        get__typename:
          type: string
        id:
          type: string
        status:
          enum:
            - OPEN
            - IN_PROGRESS
            - CANCELLED
            - INCOMPLETE
            - CLOSED
            - SCHEDULED
            - ON_HOLD
            - $UNKNOWN
          type: string
      type: object
    PageInfo1:
      properties:
        endCursor:
          type: string
        get__typename:
          type: string
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          type: string
      type: object

````