# 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 'No shipment information available yet.';
}

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

Endpoint: GET /api/external/v2/subscription-contract-details/subscription-fulfillments/{contractId}
Version: 0.0.1

## Path parameters:

  - `contractId` (integer, required)
    Contract ID

## Query parameters:

  - `api_key` (string)
    API Key (Deprecated - Use Header X-API-Key instead)

## Header parameters:

  - `X-API-Key` (string)

## Response 200 fields (application/json):

  - `get__typename` (string)

  - `id` (string)

  - `fulfillmentOrders` (object)

  - `fulfillmentOrders.nodes` (array)

  - `fulfillmentOrders.nodes.fulfillAt` (object)

  - `fulfillmentOrders.nodes.status` (string)
    Enum: "OPEN", "IN_PROGRESS", "CANCELLED", "INCOMPLETE", "CLOSED", "SCHEDULED", "ON_HOLD", "$UNKNOWN"

  - `fulfillmentOrders.pageInfo` (object)

  - `fulfillmentOrders.pageInfo.hasPreviousPage` (boolean)

  - `fulfillmentOrders.pageInfo.hasNextPage` (boolean)

  - `fulfillmentOrders.pageInfo.startCursor` (string)

  - `fulfillmentOrders.pageInfo.endCursor` (string)


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 502 fields