Orders: 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.

Use an order ID across different eCommerce APIs

Some eCommerce functionality is accessible by using an order's ID and passing it to other eCommerce APIs.

1. To retrieve transaction details, including payment IDs, pass the order ID to List Transactions For Single Order.
2. To add a payment record, pass the order ID and payment details to Add Payments.
3. To modify the payment status, pass the order ID along with the payment ID to Update Payment Status.
4. To retrieve fulfillment details, pass the order ID to List Fulfillments For Single Order.

Search for orders by customer

You can retrieve all orders placed by a specific customer using their email address.

1. Call Search Orders with a filter on buyerInfo.email. For example:

   Copy

2. The response contains an array of orders matching the filter. Use the metadata.cursors object to paginate through results if needed.

3. To get transaction details for a specific order, pass the order id to List Transactions For Single Order.

Create an order with restricted edit access

If you want to ensure that only your app can edit orders it creates, you can restrict edit access at creation time. This is useful, for example, to prevent other apps from modifying imported orders.

To create an order that only your app can edit:

1. Call Create Order and add the following to the request body's settings field:

   Copy

2. The order is created with edit access restricted to your app. Any other app that attempts to edit the order receives an ORDER_CANNOT_BE_EDITED error.

Track fulfillment status

You can retrieve fulfillment details for an order and update tracking information. An order that was manually marked as fulfilled has no fulfillments. To find when it was fulfilled, see Get the date an order was fulfilled.

1. Call List Fulfillments For Single Order with the order ID to get existing fulfillments.

2. To add a new fulfillment with tracking information, call Create Fulfillment. For example:

   Copy

3. To update tracking information on an existing fulfillment, call Update Fulfillment with the order ID, fulfillment ID, and updated tracking details.

Get the date an order was fulfilled

You can build a report of orders based on the date they were fulfilled. Where the date is stored depends on how the order was fulfilled:

• When an order is manually marked as fulfilled, for example, in the site dashboard, an ORDER_FULFILLED activity is added to the order. No fulfillment is created.
• When order items are fulfilled with fulfillments, each fulfillment has its own createdDate.

When a paid order has no shipping info, it's fulfilled automatically and the date isn't recorded. Don't use an order's updatedDate as the fulfillment date, because it changes with every update to the order.

To get the date each order was fulfilled:

1. Call Search Orders with a filter on fulfillmentStatus. For example:

   Copy

   Use metadata.cursors.next to page through all results.

2. For each order in the response, find the most recent activity in activities with an activityType of ORDER_FULFILLED. Its createdDate is the date and time the order was marked as fulfilled.

3. Call List Fulfillments For Multiple Orders with the IDs of the orders that have no ORDER_FULFILLED activity. You can specify up to 100 order IDs per call. For each order, use the createdDate of its most recent fulfillment.

4. Filter or group the orders by these dates in your code. Search Orders doesn't support filtering or sorting by activities.