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.
Many e-commerce 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:
Listen for new orders using the Order Approved webhook.
When a new order arrives, get the order ID from the webhook payload (entityId or actionEvent.body.order.id).
Call Create Fulfillment with the order ID, line items to fulfill, and tracking information. For the tracking info, specify the shipping provider (e.g., "fedex") and tracking number.
The API automatically generates the tracking link based on the provider and tracking number.
Monitor the Fulfillments Updated webhook to track status changes.
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:
Listen for new orders using the Order Approved webhook.
When a new order arrives, get the order ID from the webhook payload.
Generate or obtain the tracking URL from your custom shipping provider's system.
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.
Monitor the Fulfillments Updated webhook to track status changes.
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:
Collect the order IDs that need fulfillment processing.
Group orders by shipping provider if necessary.
Call Bulk Create Fulfillments with your list of orders and their fulfillment details. For each order, specify the line items and tracking information.
Check the response's bulk action metadata to verify all fulfillments were created successfully.
For any failed fulfillments, check the individual error messages and handle retries as needed.
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:
Call List Fulfillments for Single Order with the order ID to get current status.
As the fulfillment progresses, use Update Fulfillment to update the status. Remember to only include the status field in your update.
Listen to the Fulfillments Updated webhook to monitor status changes.
When the carrier confirms delivery, update the status to "Fulfilled".