Skip to content

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 '{
        "ids": [
            "c85ea826-5259-4866-998c-7c56129d575c",
            "e575556f-1daa-46dd-a4cc-84bcfc0a4f36",
        ],
        "financialStatuses": [
            "paid"
        ]
    }'

Response example

{
  "orders": [
    {
      "id": "c85ea826-5259-4866-998c-7c56129d575c",
      "orderReferenceId": "{{myOrderId}}",
      "customerReferenceId": "{{myCustomerId}}",
      "fulfillmentStatus": "printed",
      "financialStatus": "paid",
      "currency": "USD",
      "firstName": "Paul",
      "lastName": "Smith",
      "country": "US",
      "createdAt": "2021-01-14T12:30:03+00:00",
      "updatedAt": "2021-01-14T12:32:03+00:00",
      "orderedAt": "2021-01-14T12:32:03+00:00"
    },
    {
      "id": "e575556f-1daa-46dd-a4cc-84bcfc0a4f36",
      "orderReferenceId": "{{myOrderId}}",
      "customerReferenceId": "{{myCustomerId}}",
      "fulfillmentStatus": "printed",
      "financialStatus": "paid",
      "currency": "USD",
      "firstName": "Paul",
      "lastName": "Smith",
      "country": "US",
      "createdAt": "2021-01-14T12:30:03+00:00",
      "updatedAt": "2021-01-14T12:32:03+00:00",
      "orderedAt": "2021-01-14T12:32:03+00:00"
    }
  ]
}

Request

Parameter Type Description
ids (optional) string[] List of Gelato order ids.
orderReferenceId (optional) string Reference to your internal order id.
orderReferenceIds (optional) string[] List of references to your internal order ids.
fulfillmentStatuses (optional) string[] List of order fulfillment statuses.
financialStatuses (optional) string[] List of order financial statuses.
channels (optional) string[] List of order channels.
countries (optional) string[] List of order countries (based on shipping address).
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.
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.
offset (optional) int Offset of search request (default = 0).
limit (optional) int The maximum number of results to show on a page. (default: 50, maximum: 100)

Response

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

OrderObject

Parameter Type Description
id (required) string Gelato order id.
orderReferenceId (required) string Reference to your internal order id.
fulfillmentStatus (required) string The order current fulfillment status. Can be: created, passed, failed, canceled, printed, shipped, draft, pending_approval, not_connected, on_hold.
financialStatus (required) string The order current financial status. Can be: draft, pending, invoiced, to_be_invoiced, paid, canceled, partially_refunded, refunded and refused.
currency (optional) string The order currency.
channel (required) string The order channel. Can be: ui, api, shopify and etsy.
country (optional) string The two-character ISO 3166-1 code that identifies the country or region.
firstName (optional) string The first name of the order recipient.
lastName (optional) string The last name of the order recipient.
createdAt (required) string Date and time in ISO 8601 format when order was created.
updatedAt (required) string Date and time in ISO 8601 format when order was updated.
orderedAt (optional) string Date and time in ISO 8601 format when order was placed.