Search orders

Use the Search API to retrieves a list of orders

POST https://order.gelatoapis.com/v4/orders:search

Request example

$ curl -X POST \
   https://order.gelatoapis.com/v4/orders:search \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{
        "orderTypes": [
            "draft",
            "order"
        ],
        "countries": [
            "US",
            "DE",
            "CA"
        ]
    }'

Response example

{
  "orders": [
    {
      "channel": "shopify",
      "connectedOrderIds": [],
      "country": "US",
      "createdAt": "2024-04-04T20:59:55+00:00",
      "currency": "USD",
      "customerReferenceId": "{{myCustomerId}}",
      "financialStatus": "paid",
      "firstName": "Paul",
      "fulfillmentStatus": "shipped",
      "id": "c85ea826-5259-4866-998c-7c56129d575c",
      "itemsCount": 3,
      "lastName": "Smith",
      "orderReferenceId": "{{myOrderId}}",
      "orderType": "draft",
      "orderedAt": "2024-01-15T12:32:03+00:00",
      "storeId": "a6bf6ec0-28cb-43a5-92b0-2550f007aac5",
      "totalInclVat": "49.12",
      "updatedAt": "2024-01-15T12:32:03+00:00"      
    },
    {
      "channel": null,
      "connectedOrderIds": [],
      "country": "DE",
      "createdAt": "2024-02-04T20:59:55+00:00",
      "currency": "EUR",
      "customerReferenceId": "{{myCustomerId2}}",
      "financialStatus": "draft",
      "firstName": "Paul",
      "fulfillmentStatus": "draft",
      "id": "e575556f-1daa-46dd-a4cc-84bcfc0a4f36",
      "itemsCount": 1,
      "lastName": "Smith",
      "orderReferenceId": "{{myOrderId2}}",
      "orderType": "draft",
      "orderedAt": null,
      "storeId": null,
      "totalInclVat": "0.00",
      "updatedAt": "2024-02-05T12:32:03+00:00"
    }
  ]
}

Request

Parameter	Type	Description
channels (optional)	string[]	List of order channels.
countries (optional)	string[]	List of order countries (based on shipping address).
currencies (optional)	string[]	List of order currencies.
endDate (optional)	string[]	Show orders ordered at or created at before date (format: 2014-04-25T16:15:47-04:00). Date and time in ISO 8601 format.
financialStatuses (optional)	string[]	List of order financial statuses.
fulfillmentStatuses (optional)	string[]	List of order fulfillment statuses.
ids (optional)	string[]	List of Gelato order ids.
limit (optional)	int	The maximum number of results to show on a page. (default: 50, maximum: 100)
offset (optional)	int	Offset of search request (default = 0).
orderReferenceId (optional)	string	Reference to your internal order id.
orderReferenceIds (optional)	string[]	List of references to your internal order ids.
orderTypes (optional)	string[]	List of order types. It can be order or draft. Draft orders can be edited from the dashboard and they don't go into production until you decide to convert draft into a regular order via UI or programmatically via Order Patch API.
search (optional)	string	Search string. Show orders contain value from search in fields - shippingAddress.firstName, shippingAddress.lastName or orderReferenceId.
startDate (optional)	string[]	Show orders ordered at or created at after date (format: 2014-04-25T16:15:47-04:00). Date and time in ISO 8601 format.
storeIds (optional)	string[]	List of E-commerce store IDs identifying which store the order was placed in.

Response

Parameter	Type	Description
orders (required)	OrderObject	List of Orders matching to the search parameters

OrderObject

Parameter	Type	Description
channel (required)	string	The order channel. Can be: ui, api, shopify and etsy.
connectedOrderIds (optional)	string[]	List of connected order IDs. Used when an order needs to be produced in multiple locations for example. Read more here
country (optional)	string	The two-character ISO 3166-1 code that identifies the country or region.
createdAt (required)	string	Date and time in ISO 8601 format when order was created.
currency (optional)	string	The order currency.
financialStatus (required)	string	The order current financial status. Can be: draft, pending, invoiced, to_be_invoiced, paid, canceled, partially_refunded, refunded and refused.
firstName (optional)	string	The first name of the order recipient.
fulfillmentStatus (required)	string	The order current fulfillment status. Can be: created, passed, failed, canceled, printed, shipped, draft, pending_approval, not_connected, on_hold.
id (required)	string	Gelato order id.
itemsCount (optional)	int	The number of items in the order.
lastName (optional)	string	The last name of the order recipient.
orderReferenceId (required)	string	Reference to your internal order id.
orderType (required)	string	Type of the order. It can be order or draft. Draft orders can be edited from the dashboard and they don't go into production until you decide to convert draft into a regular order via UI or programmatically via Order Patch API.
orderedAt (optional)	string	Date and time in ISO 8601 format when order was placed.
storeId (optional)	string	E-commerce store ID identifying which store the order was placed in.
totalInclVat (optional)	string	The total amount of the order including VAT.
updatedAt (required)	string	Date and time in ISO 8601 format when order was updated.

---