GuidesRecipesAPI Reference

Fetching new orders

This guide explains how to pull new orders from Convictional.


As a Convictional Seller, you want to easily detect new orders that show up in Convictional so that you can fulfill orders quickly. We'll show you two methods to do this below. See List Orders for more details.

Method 1 - Using the order.created timestamp

You can fetch all the orders created after a certain time by using the createdMin query parameter:

GET /orders?createdMin=2021-01-01T00:00:00Z

If you check for new orders every hour then you can set createdMin to one hour before the current time in order to pull all the orders that have come in since your last check.

Note: This method is simple but also could mean some orders get overlooked if your system has downtime or if an order is created close to the scheduled interval. Read on for a method that guarantees no orders are missed.

Method 2 - Using the order.shipped status

You can fetch all orders that haven't been shipped by using the shipped query parameter:

GET /orders?shipped=false

If you fetch all unshipped orders then you are guaranteed to receive all the new orders that have recently come in, as well as some orders that you already fetched but that you haven't shipped yet. You will need to set up your own way to decide whether you're seeing an order for the first time or not. We recommend storing the order._id field on your end and using that to determine whether an order is new or not.