Order Fulfillments: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Create fulfillments with a standard shipping provider

Many eCommerce businesses use standard shipping carriers like FedEx or UPS for their deliveries. This flow shows how to create fulfillments that automatically generate tracking links when using these predefined providers.

To create a fulfillment using a standard shipping provider:

1. Listen for new orders using the Order Approved webhook.

2. When a new order arrives, get the order ID from the webhook payload (entityId or actionEvent.body.order.id).

3. Call Create Fulfillment with the order ID, line items to fulfill, and tracking information. For the tracking info, specify the shipping provider (for example, fedex) and tracking number. The tracking link is generated automatically from the provider and tracking number.

4. Monitor the Order With Fulfillments Updated webhook to track status changes.

Implement custom fulfillment provider integration

When using local carriers or specialized shipping services, you'll need to manage tracking information manually. This flow demonstrates how to create fulfillments with custom providers.

To create a fulfillment using a custom shipping provider:

1. Listen for new orders using the Order Approved webhook.

2. When a new order arrives, get the order ID from the webhook payload.

3. Generate or obtain the tracking URL from your custom shipping provider's system.

4. Call Create Fulfillment with the order ID, line items, and your custom tracking information. Include your provider name, tracking number, and the complete tracking URL.

5. Monitor the Order With Fulfillments Updated webhook to track status changes.

Process bulk fulfillments for multiple orders

For high-volume operations, you can create fulfillments for multiple orders simultaneously. This is particularly useful for batch processing of orders going to the same shipping provider.

To create bulk fulfillments:

1. Collect the order IDs that need fulfillment processing.

2. Call Bulk Create Fulfillments with your list of orders and their fulfillment details. For each order, specify the line items and tracking information. You can specify up to 100 orders per call, and each order can appear once.

3. Check bulkActionMetadata.totalFailures in the response to see whether any orders failed.

4. For each item in results where itemMetadata.success is false, check itemMetadata.error and retry as needed.

Track fulfillment status progression

Monitoring the status of fulfillments helps keep customers informed about their orders. This flow shows how to track and update fulfillment statuses throughout the delivery process.

To track fulfillment status changes:

1. Call List Fulfillments For Single Order with the order ID to get current status.

2. As the fulfillment progresses, call Update Fulfillment and specify the new status in fulfillment. Fields you don't specify aren't changed.

3. Listen to the Order With Fulfillments Updated webhook to monitor status changes.

4. When the carrier confirms delivery, call Update Fulfillment to set status to Fulfilled. The status field is informational and doesn't change the order's fulfillmentStatus.