`/orders` endpoint¶

Use the /orders endpoint to find and list orders that have been imported to DropStream.

Get orders¶

To get a sorted, filtered list of orders and their data, make a GET request to /orders.

Endpoint	`/orders`
Method	`GET`
Auth	JWT
Success status	HTTP `200`
Response (JSON)	Object containing an orders array

Filtering¶

With no parameters, all orders accessible to the authenticated user are returned from a GET /orders request.

To filter order results, specify any of the following filter parameters:

Filter param	Value type	Description
`ordered_at_min`	dateString	Get orders ordered after that dateTime.
`ordered_at_max`	dateString	Get orders ordered before that dateTime.
`created_at_min`	dateString	Get orders imported to DropStream after that dateTime.
`created_at_max`	dateString	Get orders imported to DropStream before that dateTime.
`store_id`	`id` (integer) or `name` (string)	Get orders only for the specified store. Note that the store name (e.g.`"Jane's Goods"`) may be specified instead of the id (e.g. `1234`).
`external_id`	string	Get only orders with that `external_id` (external platform's internal order id).
`external_display_id`	string	Get only orders with that `external_display_id` (external platform's user-facing order id).
`state`	string	Get only orders with the specified `fulfillment_state` (DropStream internal fulfillment status), e.g. `"pending_shipment"`.

DateStrings in filters¶

Filter dateStrings can be specified as whole or partial ISO 8601 dateTimes, for example:

"2022-12-01T05:25:00.000Z"
"2022-12-01T00:25:00-05:00"
"2022-12-01"

DateStrings can be specified in natural language, and the API will attempt to interpret them in context. For example:

"December 1st 2022"
"dec 1"
"last monday"
"two hours ago"

Tip

For precise results, specify a full ISO 8601 dateTime including calendar date, time, and time zone offset. For example,

ordered_at_min=2022-10-01T00:00:00-05:00&ordered_at_max=2022-10-02T00:00:00-05:00

would return all orders placed on October 1^st in the EST (UTC-5) time zone.

Sorting¶

By default, orders are listed by ascending id, which loosely corresponds to the chronological order that they were imported to DropStream.

To sort by other order properties, specify them by name with the sort={property} parameter. For example, sort=store_id will return orders sorted by ascending store ID.

If multiple sort parameters are specified, only the last one is used.

Pagination¶

Page-based results¶

If a page parameter is specified, responses will be "page-based", allowing individual pages of multi-page responses to be retrieved arbitrarily by index number.

Otherwise, responses will be "session-based", returning a session ID in the first response that must be specified to retrieve subsequent results in order. Sessions expire 60 seconds after their most recent request.

The number of records returned per response is set by the optional limit parameter, with a maximum of 1000 per page (default 100).

Importantly, the total maximum results for page-based requests is 10,000. To receive more than 10,000 total results, you MUST use session-based requests. If a result set is incomplete because there were more than 10,000 total, the responses will include the field "max_total_reached":true.

Session-based results¶

If a page number is not specified, responses will be session-based, returning a session_id to be specified when requesting subsequent pages. Session-based results are returned in order starting with the first page (arbitrary pages cannot be fetched), but with unlimited maximum total results.

Sessions expire 60 seconds after their last request.

The number of records returned per response is set by the optional limit parameter, with a maximum of 1000 per page (default 100).

Examples¶

Page-based¶

Example (page-based)

Page 1 (curl)

# Get page 1 of all orders ordered after Oct 1, 2022, 
# 5 a.m. UTC, sorted by store

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/orders" \
  -d "limit=100" \
  -d "page=1" \
  -d "ordered_at_min=2022-10-01T05:00:00Z" \
  -d "sort=store_id"

Page 2 (curl)

# Get page 2 with the same parameters

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/orders" \
  -d "limit=100" \
  -d "page=2" \
  -d "ordered_at_min=2022-10-01T05:00:00Z" \
  -d "sort=store_id"

Response:

Page 1 (JSON)

{
  "orders": [
    {
      "id": integer,
      "store_id": integer,
      "external_id": "string",
      "external_billing_customer_id": "string",
      "customer_email": "string",
      "external_shipping_customer_id": "string",
      "ordered_at": "dateString",
      "invoice_number": "string",
      "payment_type": "string",
      "external_warehouse_order_id": "string",
      "shipping_carrier_name": "string",
      "shipping_carrier_service_level": "string",
      "shipping_warehouse_code": "string",
      "signature_required": boolean,
      "shipping_insurance": boolean,
      "external_shipping_description": "string",
      "external_display_id": "string",
      "external_source_display_id": "string",
      "purchase_order_id": "string",
      "notes": "string",
      "shipping_notes": "string",
      "gift_message": "string",
      "batch_id": "string",
      "shipping_amount": "decimal (8.2)",
      "discount_amount": "decimal (8.2)",
      "tax_amount": "decimal (8.2)",
      "shipping_tax_amount": "decimal (8.2)",
      "third_party_account_number": "string",
      "third_party_billing_code": "string",
      "discount_codes": "string",
      "external_source_id": "string",
      "lead_source": "string",
      "packing_slip_id": "striing",
      "requested_ship_date": "dateString",
      "requested_cancel_date": "dateString",
      "payment_date": "dateString",
      "external_tags": "string (comma-delimited values)",
      "retailer_id": "string",
      "supplier_id": "string",
      "insured_amount": "decimal (8.2)",
      "terms": "string",
      "sales_rep_last_name": "string",
      "sales_rep_first_name": "string",
      "sales_rep_email": "string",
      "fulfillment_state": "string",
      "fulfillment_transitioned_at": "dateString",
      "external_type": "string",
      "fulfillment_warehouse_id": integer,
      "country_of_origin": "string (2-char code)",
      "shipment_contents": "string (16777215)",
      "declared_value": "decimal (8.2)",
      "currency_code": "USD",
      "customer_service_url": "string",
      "customer_service_email": "string",
      "customer_service_telephone": "string",
      "created_at": "dateString",
      "custom": {
        "key1": "string",
        "key2": "string"
      },
      "shipping_address": {
        "first_name": "string",
        "last_name": "string",
        "street1": "string",
        "street2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "string (2-char code)",
        "telephone": "string"
      },
      "billing_address": {
        "first_name": "string",
        "last_name": "string",
        "street1": "string",
        "street2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "string (2-char code)",
        "telephone": "string"
      },
      "order_items": [
        {
          "name": "string",
          "sku": "string",
          "upc": "string",
          "unit_price": "decimal (8.2)",
          "unit_cost": "decimal (8.2)",
          "weight": "decimal (10.2)",
          "external_order_item_id": "string",
          "discount_amount": "decimal (8.2)",
          "tax_amount": "decimal (8.2)",
          "gift_wrap": boolean,
          "external_product_id": "string",
          "customer_notes": "string",
          "vendor_id": "string",
          "vendor_part_number": "string",
          "buyer_part_number": "string",
          "color_description": "string",
          "size_description": "string",
          "drop_ship": "string",
          "product_type": "string",
          "created_at": "dateString"
          "options": [
            {
              "gift_message": "string"
            }
          ],
          "custom": {
            "gift_message": "string"
          }
        },
(other order_items, if any...)
      ]
    },
(99 more orders...)
  ],
  "page": 1,
  "limit": 100,
  "total_count": 2407,
  "total_pages": 25
}

Page 2 (JSON)

{
  "orders": [
    {
(order schema...)
    },
(99 more orders...)
  ],
  "page": 2,
  "limit": 100,
  "total_count": 2407,
  "total_pages": 25
}

HTTP

HTTP/1.1 200 OK

Session-based¶

Example (session-based)

First page (curl)

# List all orders ordered after Oct 1, 2022, 
# 5 a.m. UTC, sorted by store. Response will 
# contain a session_id to be used in the
# subsequent requests 

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/orders" \
  -d "limit=100" \
  -d "ordered_at_min=2022-10-01T05:00:00Z" \
  -d "sort=store_id"

Second page (curl)

# Get the next set of records from the session.
# The 60 second session timeout is refreshed. 
# Original params persist (limit, ordered_at_min .. )
# as does the session_id.

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/orders" \
  -d "session_id=89bb5be1-8116-4f94-af26-334a0e1d3aa2"

Response:

First page (JSON)

{
  "orders": [
    {
      "id": integer,
      "store_id": integer,
      "external_id": "string",
      "external_billing_customer_id": "string",
      "customer_email": "string",
      "external_shipping_customer_id": "string",
      "ordered_at": "dateString",
      "invoice_number": "string",
      "payment_type": "string",
      "external_warehouse_order_id": "string",
      "shipping_carrier_name": "string",
      "shipping_carrier_service_level": "string",
      "shipping_warehouse_code": "string",
      "signature_required": boolean,
      "shipping_insurance": boolean,
      "external_shipping_description": "string",
      "external_display_id": "string",
      "external_source_display_id": "string",
      "purchase_order_id": "string",
      "notes": "string",
      "shipping_notes": "string",
      "gift_message": "string",
      "batch_id": "string",
      "shipping_amount": "decimal (8.2)",
      "discount_amount": "decimal (8.2)",
      "tax_amount": "decimal (8.2)",
      "shipping_tax_amount": "decimal (8.2)",
      "third_party_account_number": "string",
      "third_party_billing_code": "string",
      "discount_codes": "string",
      "external_source_id": "string",
      "lead_source": "string",
      "packing_slip_id": "striing",
      "requested_ship_date": "dateString",
      "requested_cancel_date": "dateString",
      "payment_date": "dateString",
      "external_tags": "string (comma-delimited values)",
      "retailer_id": "string",
      "supplier_id": "string",
      "insured_amount": "decimal (8.2)",
      "terms": "string",
      "sales_rep_last_name": "string",
      "sales_rep_first_name": "string",
      "sales_rep_email": "string",
      "fulfillment_state": "string",
      "fulfillment_transitioned_at": "dateString",
      "external_type": "string",
      "fulfillment_warehouse_id": integer,
      "country_of_origin": "string (2-char code)",
      "shipment_contents": "string (16777215)",
      "declared_value": "decimal (8.2)",
      "currency_code": "USD",
      "customer_service_url": "string",
      "customer_service_email": "string",
      "customer_service_telephone": "string",
      "created_at": "dateString",
      "custom": {
        "key1": "string",
        "key2": "string"
      },
      "shipping_address": {
        "first_name": "string",
        "last_name": "string",
        "street1": "string",
        "street2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "string (2-char code)",
        "telephone": "string"
      },
      "billing_address": {
        "first_name": "string",
        "last_name": "string",
        "street1": "string",
        "street2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "string (2-char code)",
        "telephone": "string"
      },
      "order_items": [
        {
          "name": "string",
          "sku": "string",
          "upc": "string",
          "unit_price": "decimal (8.2)",
          "unit_cost": "decimal (8.2)",
          "weight": "decimal (10.2)",
          "external_order_item_id": "string",
          "discount_amount": "decimal (8.2)",
          "tax_amount": "decimal (8.2)",
          "gift_wrap": boolean,
          "external_product_id": "string",
          "customer_notes": "string",
          "vendor_id": "string",
          "vendor_part_number": "string",
          "buyer_part_number": "string",
          "color_description": "string",
          "size_description": "string",
          "drop_ship": "string",
          "product_type": "string",
          "created_at": "dateString"
          "options": [
            {
              "gift_message": "string"
            }
          ],
          "custom": {
            "gift_message": "string"
          },
        },
(other order_items, if any...)
      ]
    },
(99 more orders...)
  ],
  "session_id": "89bb5be1-8116-4f94-af26-334a0e1d3aa2",
  "page": 1,
  "limit": 100
}

Second page (JSON)

{
  "orders": [
    {
(order schema...)
    },
(99 more orders...)
  ],
  "session_id": "89bb5be1-8116-4f94-af26-334a0e1d3aa2",
  "page": 2,
  "limit": 100
}

HTTP

HTTP/1.1 200 OK

Get order¶

To get a specific order, specify its id in a GET call to /orders/{id}.

Endpoint	`/orders/{id}`
Method	`GET`
Auth	JWT
Success status	HTTP `200`
Response (JSON)	Object containing an order

Example¶

Example

Page 1 (curl)

# Get order id 123456789

curl -G \
  -H "Authorization: Bearer $JWT_TOKEN" \
  "https://api.getdropstream.com/orders/123456789"

Response:

JSON

{
  "order": {
    "id": integer,
    "store_id": integer,
    "external_id": "string",
    "external_billing_customer_id": "string",
    "customer_email": "string",
    "external_shipping_customer_id": "string",
    "ordered_at": "dateString",
    "invoice_number": "string",
    "payment_type": "string",
    "external_warehouse_order_id": "string",
    "shipping_carrier_name": "string",
    "shipping_carrier_service_level": "string",
    "shipping_warehouse_code": "string",
    "signature_required": boolean,
    "shipping_insurance": boolean,
    "external_shipping_description": "string",
    "external_display_id": "string",
    "external_source_display_id": "string",
    "purchase_order_id": "string",
    "notes": "string",
    "shipping_notes": "string",
    "gift_message": "string",
    "batch_id": "string",
    "shipping_amount": "decimal (8.2)",
    "discount_amount": "decimal (8.2)",
    "tax_amount": "decimal (8.2)",
    "shipping_tax_amount": "decimal (8.2)",
    "third_party_account_number": "string",
    "third_party_billing_code": "string",
    "discount_codes": "string",
    "external_source_id": "string",
    "lead_source": "string",
    "packing_slip_id": "striing",
    "requested_ship_date": "dateString",
    "requested_cancel_date": "dateString",
    "payment_date": "dateString",
    "external_tags": "string (comma-delimited values)",
    "retailer_id": "string",
    "supplier_id": "string",
    "insured_amount": "decimal (8.2)",
    "terms": "string",
    "sales_rep_last_name": "string",
    "sales_rep_first_name": "string",
    "sales_rep_email": "string",
    "fulfillment_state": "string",
    "fulfillment_transitioned_at": "dateString",
    "external_type": "string",
    "fulfillment_warehouse_id": integer,
    "country_of_origin": "string (2-char code)",
    "shipment_contents": "string (16777215)",
    "declared_value": "decimal (8.2)",
    "currency_code": "USD",
    "customer_service_url": "string",
    "customer_service_email": "string",
    "customer_service_telephone": "string",
    "created_at": "dateString",
    "custom": {
      "key1": "string",
      "key2": "string"
      },
    }
    "shipping_address": {
      "first_name": "string",
      "last_name": "string",
      "street1": "string",
      "street2": "string",
      "city": "string",
      "region": "string",
      "postal_code": "string",
      "country": "string (2-char code)",
      "telephone": "string"
    },
    "billing_address": {
      "first_name": "string",
      "last_name": "string",
      "street1": "string",
      "street2": "string",
      "city": "string",
      "region": "string",
      "postal_code": "string",
      "country": "string (2-char code)",
      "telephone": "string"
    },
    "order_items": [
      {
        "name": "string",
        "sku": "string",
        "upc": "string",
        "unit_price": "decimal (8.2)",
        "unit_cost": "decimal (8.2)",
        "weight": "decimal (10.2)",
        "external_order_item_id": "string",
        "discount_amount": "decimal (8.2)",
        "tax_amount": "decimal (8.2)",
        "gift_wrap": boolean,
        "external_product_id": "string",
        "customer_notes": "string",
        "vendor_id": "string",
        "vendor_part_number": "string",
        "buyer_part_number": "string",
        "color_description": "string",
        "size_description": "string",
        "drop_ship": "string",
        "product_type": "string",
        "created_at": "dateString"
        "options": [
          {
            "gift_message": "string"
          }
        ],
        "custom": {
          "gift_message": "string"
        }
      },
(other order_items, if any...)
    ]
  }
}

HTTP

HTTP/1.1 200 OK

/orders endpoint¶

Get orders¶

Filtering¶

DateStrings in filters¶

Sorting¶

Pagination¶

Page-based results¶

Session-based results¶

Examples¶

Page-based¶

Session-based¶

Get order¶

Example¶

`/orders` endpoint¶