Examples
In this section, we will explore some examples of the different queries & mutations available on the API.
Queries
Note
For better readability, all of the available fields are not included in our example queries. To navigate through the Schema and see all of the fields available, please check our Documentation section.
- uuid
- Order
- Orders
- Product
- Products
- Returns
- Browse order history
- Shipment
- Shipments
- Packs per day
- Line item picks
- Purchase Order
- Purchase Orders
- Vendors
- Inventory Changes
- Warehouse products
uuid
When using the old webhooks you might receive resource ids as numeric ids. If you need any of those ids in one of our new queries or mutations, you can use this query to retrieve the uuid
corresponding to that resource/entity numeric id as:
query {
uuid(legacy_id:100579698, entity: Order) {
data {
legacy_id
id
}
}
}
and the response should look something like this:
{
"data": {
"uuid": {
"data": {
"legacy_id": 100579698,
"id": "T3JkZXI6MTAwNTc5Njk4"
}
}
}
}
Order
This feature of the API allows to access a order’s details. To make it you should specify the order_id
:
query {
order(id: "T3JkZXI6MTAwNTc0MjM1") {
request_id
complexity
data {
id
legacy_id
order_number
shop_name
fulfillment_status
order_date
profile
required_ship_date
shipping_lines {
carrier
method
price
}
shipping_address {
first_name
last_name
address1
address2
city
state
state_code
zip
country
}
tags
line_items(first: 2) {
edges {
node {
id
sku
quantity
product_name
fulfillment_status
quantity_allocated
backorder_quantity
barcode
}
cursor
}
}
allocations {
warehouse_id
allocated_at
allocation_reference
line_items {
line_item_id
sku
quantity_allocated
is_kit_component
warehouse_id
allocated_at
allocation_reference
}
}
shipments {
id
order_id
user_id
warehouse_id
address {
name
address1
address2
city
state
country
zip
}
shipped_off_shiphero
dropshipment
}
returns {
id
reason
status
}
}
}
}
Response:
{
"data": {
"order": {
"request_id": "624ed20433a41fbf119fb950",
"complexity": 3,
"data": {
"id": "T3JkZXI6MTAwNTc0MjM1",
"legacy_id": 100574235,
"order_number": "MO519",
"shop_name": "Manual Order",
"fulfillment_status": "TESTING",
"order_date": "2019-07-16T14:46:03",
"profile": "default",
"required_ship_date": "2019-07-18T00:00:00",
"shipping_lines": {
"carrier": "amazon",
"method": "99",
"price": null
},
"shipping_address": {
"first_name": "Aaron",
"last_name": "Rubin",
"address1": "55 W RAILROAD AVE BLDG 4",
"address2": "",
"city": "GARNERVILLE",
"state": "NY",
"state_code": null,
"zip": "10923-1261",
"country": "US"
},
"tags": [],
"line_items": {
"edges": [
{
"node": {
"id": "TGluZUl0ZW06Mjk0MDc2OTEw",
"sku": "leandro-build-kit",
"quantity": 1,
"product_name": "Leandro Build Kit",
"fulfillment_status": "broken_in_sets",
"quantity_allocated": 0,
"backorder_quantity": 0,
"barcode": "1563302685"
},
"cursor": "YXJyYXljb25uZWN0aW9uOjA="
},
{
"node": {
"id": "TGluZUl0ZW06Mjk0MDc2OTI0",
"sku": "regular-kit-item-1",
"quantity": 1,
"product_name": "Regular Kit Item 1",
"fulfillment_status": "pending",
"quantity_allocated": 0,
"backorder_quantity": 1,
"barcode": "1563218450"
},
"cursor": "YXJyYXljb25uZWN0aW9uOjE="
}
]
},
"allocations": [
{
"warehouse_id": "V2FyZWhvdXNlOjY1NDU=",
"allocated_at": "2020-09-03T20:24:39",
"allocation_reference": "UGVuZGluZ1NoaXBtZW50OjI1NDI4MjU2OA==",
"line_items": [
{
"line_item_id": "TGluZUl0ZW06Mjk0MDc2OTI4",
"sku": "regular-kit-item-2",
"quantity_allocated": 1,
"is_kit_component": false,
"warehouse_id": "V2FyZWhvdXNlOjY1NDU=",
"allocated_at": "2020-09-03T20:24:39",
"allocation_reference": "UGVuZGluZ1NoaXBtZW50TGluZUl0ZW06NTM4MTU1MTQ5"
}
]
}
],
"shipments": [],
"returns": []
}
}
}
}
Orders
Similar to the order
query, you could query for, many orders using the orders
query and using a filter like:
- shop_name
- partner_order_id
- order_number
- warehouse_id
- fulfillment_status
- sku
- updated_from & updated_to
- order_date_from & order_date_to
- customer_account_id
And the Query could be something like this:
query {
orders(warehouse_id: "V2FyZWhvdXNlOjExNzkw") {
request_id
complexity
data(first: 10) {
edges {
node {
id
legacy_id
order_number
partner_order_id
shop_name
fulfillment_status
order_date
total_tax
subtotal
total_discounts
total_price
auto_print_return_label
custom_invoice_url
account_id
email
profile
packing_note
required_ship_date
flagged
saturday_delivery
ignore_address_validation_errors
priority_flag
source
third_party_shipper {
zip
account_number
country
}
gift_invoice
order_history {
created_at
information
user_id
}
allow_partial
require_signature
adult_signature_required
alcohol
expected_weight_in_oz
insurance
insurance_amount
currency
has_dry_ice
allocation_priority
allow_split
line_items(first: 10) {
edges {
node {
sku
quantity
quantity_allocated
quantity_pending_fulfillment
backorder_quantity
promotion_discount
}
}
}
}
}
}
}
}
Product
This feature of the API allows you to get information about a product. To make it you should specify the id
of the product:
query {
product(id:"UHJvZHVjdEluZm86MjY5NTg0MTAw") {
request_id
complexity
data {
id
legacy_id
account_id
name
sku
price
value
barcode
country_of_manufacture
dimensions {
weight
height
width
length
}
tariff_code
value_currency
kit
kit_build
no_air
final_sale
customs_value
customs_description
not_owned
dropship
created_at
warehouse_products {
warehouse_id
warehouse_identifier
on_hand
inventory_bin
inventory_overstock_bin
reserve_inventory
replenishment_level
reorder_amount
reorder_level
custom
}
images {
src
position
}
tags
vendors {
vendor_id
vendor_sku
}
product_note
virtual
ignore_on_invoice
ignore_on_customs
active
kit_components {
quantity
sku
}
}
}
}
Products
Similar to the product
query, you could also query for more than one product using the products
query:
query {
products {
request_id
complexity
data(first: 100) {
edges {
node {
id
legacy_id
account_id
name
sku
barcode
country_of_manufacture
dimensions {
height
width
length
weight
}
tariff_code
kit
kit_build
no_air
final_sale
customs_value
customs_description
not_owned
dropship
needs_serial_number
thumbnail
large_thumbnail
created_at
updated_at
product_note
virtual
ignore_on_invoice
ignore_on_customs
active
warehouse_products {
warehouse_id
on_hand
}
images {
src
}
tags
kit_components {
sku
quantity
}
}
}
}
}
}
Note
The warehouse_products
the section will allow you to see inventory levels and different characteristics of the product on each of your warehouses.
Returns
We now have a more robust and complete way of accessing returns by using both the returns and return queries.
For example, if we needed to get information about a specific return, we will use the return Query, specifying the id.
The query should look something like this:
query {
return(id: "UmV0dXJuOjc1MzYyNA==") {
request_id
complexity
data {
id
legacy_id
account_id
order_id
reason
status
label_type
label_cost
total_items_expected
total_items_received
total_items_restocked
cost_to_customer
shipping_carrier
shipping_method
address {
address1
address2
city
state
country
zip
}
line_items {
id
line_item_id
warehouse_id
product_id
return_id
quantity
condition
}
}
}
}
And the response should look something like this:
{
"data": {
"return": {
"request_id": "5f46b7577b7f0383ea23378e",
"complexity": 1,
"data": {
"id": "UmV0dXJuOjEzMjkwMDE=",
"legacy_id": 1329001,
"account_id": "QWNjb3VudDo2MzM0",
"order_id": "T3JkZXI6MTI3MTQ4NDU3",
"reason": "Too small",
"status": "warehouse complete",
"label_type": "FREE",
"label_cost": "0.00",
"total_items_expected": 1,
"total_items_received": 0,
"total_items_restocked": 0,
"cost_to_customer": "0.00",
"shipping_carrier": "UPS",
"shipping_method": "Ground",
"address": {
"address1": "55 W RAILROAD AVE",
"address2": "BLDG 4",
"city": "GARNERVILLE",
"state": "NY",
"country": "US",
"zip": "10923-1261"
},
"line_items": [
{
"id": "UmV0dXJuSXRlbToyMTM4NTI4",
"line_item_id": "TGluZUl0ZW06MzcwODgwNjMw",
"warehouse_id": "V2FyZWhvdXNlOjExNzkw",
"product_id": "UHJvZHVjdDozMDE3MDU0MzI=",
"return_id": "UmV0dXJuOjEzMjkwMDE=",
"quantity": 1,
"condition": "Good"
}
]
}
}
}
}
Note
For more information about returns visit our Returns section
Browse order history
This new feature of the API allows navigating through an order’s history. To make it you should specify the order_id
:
query {
order_history(order_id: "T3JkZXI6OTkxMzAxMjE=") {
request_id
complexity
data(first: 2) {
edges {
node {
id
order_id
account_id
order_number
information
order {
shop_name
fulfillment_status
order_date
email
profile
packing_note
required_ship_date
shipping_address {
first_name
last_name
company
address1
address2
city
state
state_code
zip
country
country_code
email
phone
}
}
}
cursor
}
}
}
}
Response:
{
"data": {
"order_history": {
"request_id": "5d3b5f77233bd12e389388dc",
"complexity": 3,
"data": {
"edges": [
{
"node": {
"id": "T3JkZXJIaXN0b3J5OjIxMDk4MzkzNQ==",
"order_id": "T3JkZXI6OTkxMzAxMjE=",
"account_id": "QWNjb3VudDozODAx",
"order_number": "MO506",
"information": "Order Created.",
"order": {
"shop_name": "Manual Order",
"fulfillment_status": "pending",
"order_date": "2019-06-25T13:46:21+00:00",
"ready_to_ship": false,
"email": null,
"profile": "default",
"packing_note": null,
"required_ship_date": "2019-06-27T00:00:00+00:00",
"shipping_address": {
"first_name": null,
"last_name": null,
"company": null,
"address1": "54 W RAILROAD AVE BLDG 4",
"address2": "BLDG 4",
"city": "GARNERVILLE",
"state": "NY",
"state_code": null,
"zip": "10923",
"country": "US",
"country_code": null,
"email": null,
"phone": "8556055222"
}
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjA="
},
{
"node": {
"id": "T3JkZXJIaXN0b3J5OjIxMTAzNTcxNA==",
"order_id": "T3JkZXI6OTkxMzAxMjE=",
"account_id": "QWNjb3VudDozODAx",
"order_number": null,
"information": "Order lock was cleared manually by using the <strong>\"Remove Order Locks\"</strong> button for this user.",
"order": {
"shop_name": "Manual Order",
"fulfillment_status": "pending",
"order_date": "2019-06-25T13:46:21+00:00",
"email": null,
"profile": "default",
"packing_note": null,
"required_ship_date": "2019-06-27T00:00:00+00:00",
"shipping_address": {
"first_name": null,
"last_name": null,
"company": null,
"address1": "54 W RAILROAD AVE BLDG 4",
"address2": "BLDG 4",
"city": "GARNERVILLE",
"state": "NY",
"state_code": null,
"zip": "10923",
"country": "US",
"country_code": null,
"email": null,
"phone": "8556055222"
}
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjE="
}
]
}
}
}
}
Shipment
If you want to query for a specific shipment, you could query for a shipment, using the shipment_id
, for example:
query{
shipment(id:"U2hpcG1lbnQ6ODAxOTAwMTc="){
request_id
complexity
data{
id
legacy_id
order_id
user_id
warehouse_id
pending_shipment_id
address {
name
address1
address2
city
state
country
zip
phone
}
shipped_off_shiphero
dropshipment
created_date
line_items(first: 10) {
edges {
node {
line_item_id
quantity
}
}
}
shipping_labels {
id
legacy_id
account_id
tracking_number
carrier
shipping_name
shipping_method
cost
profile
packing_slip
warehouse
insurance_amount
carrier_account_id
source
created_date
}
}
}
}
Response:
{
"data": {
"shipment": {
"request_id": "5f46b99994b45764ed356d52",
"complexity": 11,
"data": {
"id": "U2hpcG1lbnQ6ODAxOTAwMTc=",
"legacy_id": 80190017,
"order_id": "T3JkZXI6MTI3MTQ4NDU3",
"user_id": null,
"warehouse_id": "V2FyZWhvdXNlOjExNzkw",
"pending_shipment_id": "UGVuZGluZ1NoaXBtZW50OjIwODczODAzOA==",
"address": null,
"shipped_off_shiphero": false,
"dropshipment": false,
"created_date": "2020-05-15T04:23:06+00:00",
"line_items": {
"edges": [
{
"node": {
"line_item_id": "TGluZUl0ZW06MzcwODgwNjMw",
"quantity": 1
}
}
]
},
"shipping_labels": [
{
"id": "U2hpcHBpbmdMYWJlbDo1NTk4MDYyMQ==",
"legacy_id": 55980621,
"account_id": "QWNjb3VudDo2MzM0",
"tracking_number": null,
"carrier": "genericlabel",
"shipping_name": "Manual Order Shipping Method",
"shipping_method": "genericlabel",
"cost": "0.00",
"profile": "default",
"packing_slip": null,
"warehouse": "Primary",
"insurance_amount": "0.00",
"carrier_account_id": null,
"source": "endeavour mobil",
"created_date": "2020-05-15T04:23:06+00:00"
}
]
}
}
}
}
Shipments
This new feature of the API allows you to get all the shipments made on an order by using the order_id
filter, or even get all the shipments made on a specific time frame, for example:
query {
shipments(order_id: "141683690") {
request_id
complexity
data {
edges {
node {
id
legacy_id
order_id
user_id
warehouse_id
pending_shipment_id
address {
name
address1
address2
city
state
country
zip
phone
}
shipped_off_shiphero
dropshipment
created_date
line_items(first: 10) {
edges {
node {
line_item_id
quantity
}
}
}
shipping_labels {
id
legacy_id
account_id
tracking_number
carrier
shipping_name
shipping_method
cost
profile
packing_slip
warehouse
insurance_amount
carrier_account_id
source
created_date
}
}
}
}
}
}
Response:
{
"data": {
"shipments": {
"request_id": "5f3aeced950bae264fdd84d6",
"complexity": 1001,
"data": {
"edges": [
{
"node": {
"id": "U2hpcG1lbnQ6OTQyMzY4NjU=",
"legacy_id": 94236865,
"order_id": "T3JkZXI6MTQxNjgzNjkw",
"user_id": null,
"warehouse_id": "V2FyZWhvdXNlOjExNzkw",
"pending_shipment_id": "UGVuZGluZ1NoaXBtZW50OjI0NDk4MTA5Ng==",
"address": null,
"shipped_off_shiphero": false,
"dropshipment": false,
"created_date": "2020-08-14T02:44:41+00:00",
"line_items": {
"edges": [
{
"node": {
"line_item_id": "TGluZUl0ZW06NDA0NDM2MzQ0",
"quantity": 1
}
}
]
},
"shipping_labels": [
{
"id": "U2hpcHBpbmdMYWJlbDo2Nzk5NDkwMA==",
"legacy_id": 67994900,
"account_id": "QWNjb3VudDo2MzM0",
"tracking_number": null,
"carrier": "genericlabel",
"shipping_name": "Manual Order Shipping Method",
"shipping_method": "genericlabel",
"cost": "0.00",
"profile": "default",
"packing_slip": null,
"warehouse": "Primary",
"insurance_amount": "0.00",
"carrier_account_id": null,
"source": "shiphero v3 web",
"created_date": "2020-08-14T02:44:41+00:00"
}
]
}
}
]
}
}
}
}
You can also filter by using date_from
or date_to
.
Packs per day
Gets the detail of each shipment’s package between the specified dates. Results are sorted by date, warehouse and user, but they can be filtered by warehouse_id
if only interested in the packages from a particular warehouse.
The sorting can be overridden by specifying any other field or list of fields from the output type. In the following example, we want to retrieve certain info about what a user has packed on 2019-05-03. So the query for that would be something like:
query {
packs_per_day(
user_id: "VXNlcjo5MTIz"
date_from: "2019-05-03"
date_to: "2019-05-04"
) {
request_id
complexity
data {
edges {
node {
id
shipment_id
warehouse_id
total_items
unique_items
barcodes_scanned
created_at
order {
id
order_number
}
}
cursor
}
}
}
}
And the response would look something like this:
{
"data": {
"packs_per_day": {
"request_id": "5d3bd22669af712be6bacd54",
"complexity": 101,
"data": {
"edges": [
{
"node": {
"id": "UGFja1Jlc3VsdDoyOTkwNDc0Nw==",
"shipment_id": "U2hpcG1lbnQ6NTA3OTI2ODI=",
"warehouse_id": "V2FyZWhvdXNlOjY1NDU=",
"total_items": 1,
"unique_items": 1,
"barcodes_scanned": 0,
"created_at": "2019-05-03T20:11:05+00:00",
"order": {
"id": "T3JkZXI6OTYwMzI2NjU=",
"order_number": "MO451"
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjA="
},
{
"node": {
"id": "UGFja1Jlc3VsdDoyOTkwNTgzOQ==",
"shipment_id": "U2hpcG1lbnQ6NTA3OTQxNzg=",
"warehouse_id": "V2FyZWhvdXNlOjY1NDU=",
"total_items": 2,
"unique_items": 2,
"barcodes_scanned": 0,
"created_at": "2019-05-03T20:32:12+00:00",
"order": {
"id": "T3JkZXI6OTE3MDM5MTg=",
"order_number": "MO335"
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjE="
},
{
"node": {
"id": "UGFja1Jlc3VsdDoyOTkwNjI5Mg==",
"shipment_id": "U2hpcG1lbnQ6NTA3OTQ3MDU=",
"warehouse_id": "V2FyZWhvdXNlOjY1NDU=",
"total_items": 1,
"unique_items": 1,
"barcodes_scanned": 0,
"created_at": "2019-05-03T20:40:52+00:00",
"order": {
"id": "T3JkZXI6OTU2NzQ1MTQ=",
"order_number": "MO420"
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjI="
}
]
}
}
}
}
Line items pick
Gets the detail of each line item picked between the specified dates. Results are sorted by date, warehouse, and user, but they can be filtered by warehouse_id
if only interested in the picks from a particular warehouse. The sorting can be overridden by specifying any other field or list of fields from the output type.
For example, if we wanted to retrieve certain info about what items had been picked on 2019-04-30.
query {
picks_per_day(date_from: "2019-04-30", date_to: "2019-05-01") {
request_id
complexity
data {
edges {
node {
id
user_id
tote_id
line_item_id
location_id
order_id
order_number
user_first_name
user_last_name
inventory_bin
sku
quantity
picked_quantity
pick_type
barcode_scanned
created_at
}
cursor
}
}
}
}
And the response would look something like this:
{
"data": {
"picks_per_day": {
"request_id": "5d3bd9ee370a8cb90b7a8013",
"complexity": 101,
"data": {
"edges": [
{
"node": {
"id": "UGlja1Jlc3VsdDoxOTg0MzQ5OQ==",
"user_id": "VXNlcjo5MTIz",
"tote_id": "VG90ZToxMTk3OTc=",
"line_item_id": "TGluZUl0ZW06Mjc4NDI2MDUw",
"location_id": "QmluOjA=",
"order_id": "T3JkZXI6OTU3MjQyNzk=",
"order_number": "MO425",
"user_first_name": "Tom",
"user_last_name": "Wingord",
"inventory_bin": null,
"sku": "12347944271944",
"quantity": 1,
"picked_quantity": 1,
"pick_type": null,
"barcode_scanned": "No",
"created_at": "2019-04-30T06:48:29+00:00"
},
"cursor": "YXJyYXljb25uZWN0aW9uOjA="
},
{
"node": {
"id": "UGlja1Jlc3VsdDoxOTg0MzUwMg==",
"user_id": "VXNlcjo5MTIz",
"tote_id": "VG90ZToxMTk3OTc=",
"line_item_id": "TGluZUl0ZW06Mjc4NDI2MDQ5",
"location_id": "QmluOjA=",
"order_id": "T3JkZXI6OTU3MjQyNzk=",
"order_number": "MO425",
"user_first_name": "Tom",
"user_last_name": "Wingord",
"inventory_bin": null,
"sku": "12280811454536",
"quantity": 1,
"picked_quantity": 1,
"pick_type": null,
"barcode_scanned": "No",
"created_at": "2019-04-30T06:48:32+00:00"
},
"cursor": "YXJyYXljb25uZWN0aW9uOjE="
},
{
"node": {
"id": "UGlja1Jlc3VsdDoxOTg0MzUwOA==",
"user_id": "VXNlcjo5MTIz",
"tote_id": "VG90ZToxMTk3OTc=",
"line_item_id": "TGluZUl0ZW06Mjc4NDI2MDQ3",
"location_id": "QmluOjA=",
"order_id": "T3JkZXI6OTU3MjQyNzk=",
"order_number": "MO425",
"user_first_name": "Tom",
"user_last_name": "Wingord",
"inventory_bin": null,
"sku": "12838025822280",
"quantity": 1,
"picked_quantity": 1,
"pick_type": null,
"barcode_scanned": "No",
"created_at": "2019-04-30T06:48:35+00:00"
},
"cursor": "YXJyYXljb25uZWN0aW9uOjI="
}
]
}
}
}
}
Purchase Order
With the purchase_order
query, you can get the information about a purchase order, using the order_id
For example:
query {
purchase_order(id: "473868") {
request_id
complexity
data {
id
legacy_id
po_number
account_id
warehouse_id
vendor {
id
legacy_id
name
email
account_number
account_id
address {
name
address1
address2
city
state
country
zip
phone
}
currency
internal_note
default_po_note
logo
partner_vendor_id
created_at
}
created_at
po_date
date_closed
packing_note
fulfillment_status
po_note
description
subtotal
discount
total_price
tax
shipping_method
shipping_carrier
shipping_name
shipping_price
tracking_number
pdf
images
payment_method
payment_due_by
payment_note
locking
locked_by_user_id
line_items(first: 100) {
edges {
node {
id
legacy_id
po_id
account_id
warehouse_id
vendor_id
po_number
sku
barcode
vendor_sku
product_id
variant_id
quantity
quantity_received
quantity_rejected
price
product_name
option_title
expected_weight_in_lbs
fulfillment_status
sell_ahead
note
partner_line_item_id
updated_at
created_at
}
}
}
}
}
}
Purchase Orders
With the purchase_orders
query, you can get the information about many purchase orders and filter by
- sku
- warehouse_id
- created_from & created_to
- po_date_from & po_date_to (a.k.a Expected Date)
- customer_account_id
For example:
query {
purchase_orders(warehouse_id:"V2FyZWhvdXNlOjExNzkw") {
request_id
complexity
data(first: 2) {
edges {
node {
id
legacy_id
po_number
account_id
warehouse_id
vendor_id
created_at
po_date
date_closed
packing_note
fulfillment_status
po_note
description
subtotal
discount
total_price
tax
shipping_method
shipping_carrier
shipping_name
shipping_price
tracking_number
pdf
images
payment_method
payment_due_by
payment_note
locking
locked_by_user_id
}
}
}
}
}
Vendors
To get the list of all available Vendors, you can use the vendor’s query, which is something like this:
query {
vendors {
request_id
complexity
data(first: 10) {
edges {
node {
id
legacy_id
name
email
account_number
account_id
address {
name
address1
address2
city
state
country
zip
phone
}
currency
internal_note
default_po_note
logo
partner_vendor_id
created_at
}
}
}
}
}
Inventory Changes
You can also use this query to get all the inventory changes made to one SKU, for example:
query {
inventory_changes(sku: "1122334888") {
request_id
complexity
data(first: 10) {
edges {
node {
user_id
account_id
warehouse_id
sku
previous_on_hand
change_in_on_hand
reason
cycle_counted
location_id
created_at
location {
id
legacy_id
account_id
warehouse_id
name
zone
pickable
sellable
is_cart
temperature
last_counted
created_at
}
}
}
}
}
}
This query slightly changes if you are on Dynamic or Static Slotting. For example, Location will only populate for Dynamic Slotting accounts.
Other filters available for this Query can be:
- Location ID
- Location Name
- Date From
- Date To
Warehouse products
Using the warehouse_id
you can retreive the products from that warehouse, for example:
query {
warehouse_products(warehouse_id: "V2FyZWhvdXNlOjgwNzU=") {
request_id
complexity
data(first: 2) {
edges {
node {
id
account_id
on_hand
inventory_bin
reserve_inventory
reorder_amount
reorder_level
custom
warehouse {
id
dynamic_slotting
profile
}
product {
id
name
sku
}
}
cursor
}
}
}
}
And the response should look something like this:
{
"data": {
"warehouse_products": {
"request_id": "5d3bdbbf69af712be6bacd5c",
"complexity": 3,
"data": {
"edges": [
{
"node": {
"id": "UHJvZHVjdDoyODkxOTYyNjY=",
"account_id": "QWNjb3VudDozODAx",
"on_hand": 0,
"inventory_bin": null,
"reserve_inventory": 0,
"reorder_amount": 1,
"reorder_level": 0,
"custom": false,
"warehouse": {
"id": "V2FyZWhvdXNlOjgwNzU=",
"dynamic_slotting": false,
"profile": "default"
},
"product": {
"id": "UHJvZHVjdEluZm86MjYyODc2NDA3",
"name": "8th of LA Short Overalls- Ally Wash Large",
"sku": "12258196226120"
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjA="
},
{
"node": {
"id": "UHJvZHVjdDoyODcxNTM4OTA=",
"account_id": "QWNjb3VudDozODAx",
"on_hand": 0,
"inventory_bin": null,
"reserve_inventory": 0,
"reorder_amount": 1,
"reorder_level": 0,
"custom": false,
"warehouse": {
"id": "V2FyZWhvdXNlOjgwNzU=",
"dynamic_slotting": false,
"profile": "default"
},
"product": {
"id": "UHJvZHVjdEluZm86MjYyODc5NTI5",
"name": "Deep Mint Ombre Hoodie X-Small",
"sku": "12266021355592"
}
},
"cursor": "YXJyYXljb25uZWN0aW9uOjE="
}
]
}
}
}
}
Mutations
- Order Create
- Order Update
- Inventory
- Product Create
- Product Update
- Vendor Create
- Vendor Add/Remove Product
- Returns
- Kits
- Purchase Order Create
- Shipment Create
- Lot Create
- Lot Update
In this section we will explore some example on how we can create/modify data through Mutations.
Note
For better readability, all of the available fields are not included in our example queries. We also will be using non 3PL accounts, so in case you have make a Mutation for a 3PL’s client the customer_account_id has to be added on the query. To navigate through the Schema and see all of the fields available, please check our Documentation section.
Warning
Orders that belong to a natively connected store should not also be created from via the Public API as this can cause issues when the order imports from the store. If orders do not import as expected please reach out to our support team for assistance.
Order Create
To create an order you will have to use the order_create
mutation. For example, for the following:
- Order number: 11223344
- Product SKU: testSKU12345
- Product Quantity: 2.
The mutation will look something like this:
mutation {
order_create(
data: {
order_number: "11223344"
shop_name: "ExampleShop"
fulfillment_status: "pending"
order_date: "2019-07-29"
total_tax: "29.00"
subtotal: "150.00"
total_discounts: "20.00"
total_price: "159.00"
shipping_lines: {
title: "UPS"
price: "0.00"
carrier: "UPS"
method: "Ground"
}
shipping_address: {
first_name: "John"
last_name: "Johnson"
company: "The Johnson Co"
address1: "2543 Duck St."
address2: "Apt. 2"
city: "Oklahoma"
state: "Oklahoma"
state_code: "OK"
zip: "73008"
country: "US"
country_code: "US"
email: "johnjohnsonco@johnsonco.com"
phone: "5555555555"
}
billing_address: {
first_name: "John"
last_name: "Johnson"
company: "The Johnson Co"
address1: "2543 Duck St."
address2: "Apt. 2"
city: "Oklahoma"
state: "OK"
state_code: "OK"
zip: "73008"
country: "US"
country_code: "US"
email: "johnjohnsonco@johnsonco.com"
phone: "5555555555"
}
line_items: {
sku: "testSKU12345"
partner_line_item_id: "282960815"
quantity: 2
price: "150.00"
product_name: "Example Product"
fulfillment_status: "pending"
quantity_pending_fulfillment: 2
warehouse_id: "V2FyZWhvdYNlOjgwNzU="
}
required_ship_date: "2019-08-29"
}
) {
request_id
complexity
order {
id
order_number
shop_name
fulfillment_status
order_date
total_tax
subtotal
total_discounts
total_price
custom_invoice_url
account_id
email
profile
packing_note
required_ship_date
shipping_address {
first_name
last_name
company
address1
address2
city
state
state_code
zip
country
country_code
email
phone
}
line_items(first: 1) {
edges {
node {
id
sku
product_id
quantity
product_name
fulfillment_status
quantity_pending_fulfillment
quantity_allocated
backorder_quantity
eligible_for_return
customs_value
warehouse_id
locked_to_warehouse_id
}
}
}
}
}
}
Order Update
If you want to update, for example, the shipping address on an order, you will have to use the order_update
mutation, and with the order_id
send the following:
mutation {
order_update(
data: {
order_id: "T3JkZXI6MTQxODk1Mzc4"
packing_note: "Some note for the Packer"
profile: "default"
priority_flag:true
shipping_address: {
address1: "2543 Duck St."
address2: "Apt. 2"
city: "Oklahoma"
state: "OK"
state_code: "OK"
zip: "73008"
country: "US"
country_code: "US"
email: "johnjohnsonco@johnsonco.com"
phone: "5555555555"
}
}
) {
request_id
complexity
}
}
Note
partner_line_item_id should be a unique identifier across all the orders in the store.
Note
For updating the fulfillment_status, the order_update_fulfillment_status mutation should be used.
Inventory
To change inventory you need to use the inventory_add mutation, but it’s the same logic as inventory_remove
.
Let’s say you want to add a quantity of 1000 to a product that has 0 stock and its located on one of our warehouses.
The Mutation would look like:
mutation{
inventory_add(data:{
sku:"12258196226120",
warehouse_id:"V2FyZWhvdXNlOjgwNzU=",
quantity:1000
}){
request_id
complexity
warehouse_product{
id
account_id
on_hand
inventory_bin
}
}
}
And the response for it should be something like this:
{
"data": {
"inventory_add": {
"request_id": "5d3facf3efa03bdc83f97f10",
"complexity": 10,
"warehouse_product": {
"id": "UHJvZHVjdDoyODkxOTYyNjY=",
"account_id": "QWNjb3VudDozODAx",
"on_hand": 1000,
"inventory_bin": null,
}
}
}
}
Note
- If it’s a 3PL’s account, inventory should be altered using the 3PL account_id and specifying the customer_account_id
- To make Bulk Operations or manage different Bins(Dynamic Slotting Locations) these mutations are also available.
Product
For example, to create a product, the Mutation should be something like this:
mutation {
product_create(
data: {
name: "wood chair"
sku: "123woodchair"
warehouse_products: {
warehouse_id: "V2FyZWhvdXNlOjY1NDU="
on_hand: 130
price: "23.00"
value: "15.00"
inventory_bin: "Bin A1"
reserve_inventory: 0
replenishment_level: 1
reorder_level: 1
reorder_amount: 20
custom: false
}
barcode: "2233443355chair"
country_of_manufacture: "US"
dimensions: { weight: "12", height: "25", width: "10", length: "25" }
kit: false
kit_build: false
no_air: false
final_sale: false
customs_value: "1.00"
not_owned: true
dropship: false
}
) {
request_id
complexity
product {
id
legacy_id
account_id
name
sku
barcode
country_of_manufacture
dimensions {
weight
height
width
length
}
tariff_code
kit
kit_build
no_air
final_sale
customs_value
customs_description
not_owned
dropship
created_at
}
}
}
And the response should look something like this:
{
"data": {
"product_create": {
"request_id": "5d3fd355204bb3f0360dfe8f",
"complexity": 10,
"product": {
"id": "UHJvZHVjdEluZm86MjY2MDU0NjIx",
"legacy_id": 266054621,
"account_id": "QWNjb3VudDozODAx",
"name": "wood chair",
"sku": "123woodchair",
"barcode": "2233443355chair",
"country_of_manufacture": "US",
"dimensions": {
"weight": "12.00000000",
"height": "25.00000000",
"width": "10.00000000",
"length": "25.00000000"
},
"tariff_code": null,
"kit": false,
"kit_build": false,
"no_air": false,
"final_sale": false,
"customs_value": "1.0000",
"customs_description": null,
"not_owned": true,
"dropship": false,
"created_at": "2019-07-30T05:19:17+00:00"
}
}
}
}
Product update
For example, to update a product’s dimensions, you will need to specify the product SKU, and the Mutation should be something like this:
mutation {
product_update(
data: {
sku: "1122334457"
dimensions: {
weight: "1.00"
height: "1.00"
width: "1.00"
length: "1.00"
}
}
) {
request_id
complexity
}
}
Note
For better readability, all of the available fields are not included in our example queries. To navigate through the Schema and see all of the fields available, please check our Documentation section.
Vendor
For this example we will create a Vendor using the vendor_create
Mutation.
mutation {
vendor_create(
data: {
name: "TestVendorCreate"
email: "testvendor@shiphero.com"
account_number: "11111111"
address: {
name: "The Johnson Co"
address1: "2543 Duck St."
address2: "Apt. 2"
city: "Oklahoma"
state: "Oklahoma"
zip: "73008"
country: "US"
phone: "5555555555"
}
currency: "USD"
default_po_note: "Default Note"
}
) {
request_id
complexity
vendor {
id
legacy_id
name
email
account_number
account_id
address {
name
address1
address2
city
state
country
zip
phone
}
currency
default_po_note
created_at
}
}
}
And the response should look something like this:
{
"data": {
"vendor_create": {
"request_id": "5d3fc85c0601361d5019d3eb",
"complexity": 5,
"vendor": {
"id": "VmVuZG9yOjE1NjE4Nw==",
"legacy_id": 156187,
"name": "TestVendorCreate",
"email": "testvendor@shiphero.com",
"account_number": "11111111",
"account_id": "QWNjb3VudDozODAx",
"address": {
"name": null,
"address1": "2543 Duck St.",
"address2": "Apt. 2",
"city": "Oklahoma",
"state": "Oklah",
"country": "US",
"zip": "73008",
"phone": "5555555555"
},
"currency": "USD",
"default_po_note": "Default Note",
"created_at": "2019-07-30T04:32:28+00:00"
}
}
}
}
Vendor Add/Remove Product
To be able to add products to a specific Vendor you will need to use the vendor_add_product
mutation.
The required fields for this, are vendor_id
and sku
, for example:
mutation {
vendor_add_product(
data: { vendor_id: "VmVuZG9yOjMxOTcxOA==", sku: "45933041" }
) {
request_id
complexity
}
}
This same applies to vendor_remove_product
mutation.
Kit
To create a Kit you have to use the kit_build
Mutation, this is:
mutation {
kit_build(
data: {
sku: "KitSKU"
components: [
{ sku: "Component1", quantity: 1 }
{ sku: "Component2", quantity: 1 }
]
kit_build: false
warehouse_id: "V2FyZW4junNlOjY1NDU="
}
) {
request_id
complexity
product {
id
sku
components {
id
sku
}
}
}
}
Where:
- KitSKU, Component1, and Component2 must already exist in that specific warehouse.
kit_build
: is if you need this Kit to be a Build Kit or not, the default will go to NO (false)
And then, if you need to remove a component from the kit, you can use the kit_remove_components
mutation:
mutation {
kit_remove_components(
data: {
sku: "KitSKU"
components: [{ sku: "Component1" }]
}
) {
request_id
complexity
product {
id
sku
components {
id
sku
}
}
}
}
If you also need to clear a Kit (disassemble the kit from its components in ALL warehouses) you can use the kit_clear
mutation:
mutation {
kit_clear(data: { sku: "1122334495" }) {
request_id
complexity
}
}
Purchase Order
To create a purchase order you have to use the purchase_order_create
Mutation, for example:
mutation {
purchase_order_create(
data: {
po_date: "2020-01-01"
po_number: "TestPOExample"
subtotal: "230.00"
tax: "2.30"
shipping_price: "0.00"
total_price: "230.00"
warehouse_id: "V2FyZWhvdXNlOjgwNzU="
line_items: [
{
sku: "testSKU12345"
quantity: 5
expected_weight_in_lbs: "1.00"
vendor_id: "VmVuZG9yOjE1NjE2Mw=="
quantity_received: 0
quantity_rejected: 0
price: "230.00"
product_name: "Product for testing Purchase Orders"
fulfillment_status: "pending"
sell_ahead: 0
}
]
fulfillment_status: "pending"
discount: "0.00"
vendor_id: "VmVuZG9yOjE1NjE2Mw=="
}
) {
request_id
complexity
purchase_order {
id
po_number
account_id
warehouse_id
vendor_id
created_at
po_date
date_closed
packing_note
fulfillment_status
po_note
description
subtotal
discount
total_price
tax
shipping_method
shipping_carrier
shipping_name
shipping_price
tracking_number
payment_method
payment_due_by
payment_note
locking
locked_by_user_id
line_items(first: 1) {
edges {
node {
id
sku
}
}
}
}
}
}
Shipment
To create a shipment for a specific order, you have to use the shipment_create
Mutation, where you can specify a label if needed, for example:
mutation {
shipment_create(
data: {
order_id: "1203948237"
warehouse_id: "V2FyZWhvdXNlOjY1NDU="
address: {
name: "John"
address1: "2543 Johnson St."
address2: "Apt. 2"
city: "Oklahoma"
state: "Oklahoma"
zip: "73008"
country: "US"
phone: "5555555555"
}
line_items: { line_item_id: "111223344", quantity: 1 }
labels: {
address: {
name: "John"
address1: "2543 Johnson St."
address2: "Apt. 2"
city: "Oklahoma"
state: "Oklahoma"
zip: "73008"
country: "US"
phone: "5555555555"
}
carrier: "UPS"
shipping_name: "UPS - Ground"
shipping_method: "Ground"
cost: "0.00"
dimensions: { weight: "12", height: "12", width: "12", length: "12" }
label: {
paper_pdf_location: "exampleurl.com"
thermal_pdf_location: "exampleurl.com"
pdf_location: "exampleurl.com"
}
line_item_ids: "111223344"
tracking_number: "1234434242444444434"
}
notify_customer_via_shiphero: true
notify_customer_via_store: true
shipped_off_shiphero:true
profile: default
}
) {
request_id
complexity
shipment {
id
legacy_id
order_id
user_id
warehouse_id
pending_shipment_id
address {
name
address1
address2
city
state
country
zip
phone
}
picked_up
needs_refund
refunded
delivered
shipped_off_shiphero
dropshipment
created_date
line_items(first: 2) {
edges {
node {
id
line_item_id
quantity
}
}
}
}
}
}
Returns
This feature allows you to generate a return for a specific order. The mutation should be something like this:
mutation {
return_create(
data: {
order_id: "102360573"
warehouse_id: "6545"
return_reason: "No longer wants"
label_type: FREE
label_cost: "1.00"
address: {
name: "Tester One"
address1: "55 W RAILROAD AVE"
address2: "BLDG 4"
city: "GARNERVILLE"
state: "NY"
country: "US"
zip: "10923-1261"
phone: "8556055222"
}
dimensions: {
weight: "1.00"
height: "1.00"
width: "1.00"
length: "1.00"
}
shipping_carrier: "UPS"
shipping_method: "UPS Ground"
line_items: {
sku: "12258196226120"
quantity: 1
return_reason: "No longer wants"
condition: "new"
}
tracking_number: "12345678910"
}
) {
request_id
complexity
return {
id
order_id
reason
status
label_type
label_cost
shipping_carrier
shipping_method
address {
name
address1
address2
city
state
country
zip
phone
}
line_items {
id
line_item_id
product_id
quantity
reason
}
created_at
}
}
}
And the response:
{
"data": {
"return_create": {
"request_id": "5d547c8e47de2ba3e95322f3",
"complexity": 10,
"return": {
"id": "UmV0dXJuOjc2MTQwMg==",
"order_id": "T3JkZXI6MTAyMzYwNTcz",
"reason": "No longer wants",
"status": "pending",
"label_type": "FREE",
"label_cost": "1.00",
"shipping_carrier": "UPS",
"shipping_method": "UPS Ground",
"address": {
"name": null,
"address1": "55 W RAILROAD AVE",
"address2": "BLDG 4",
"city": "GARNERVILLE",
"state": "NY",
"country": "US",
"zip": "10923-1261",
"phone": null
},
"line_items": [
{
"id": "UmV0dXJuSXRlbToxMjI1MzEw",
"line_item_id": "TGluZUl0ZW06Mjk5Njc5OTEy",
"product_id": "UHJvZHVjdDoyODI5NjA4MTU=",
"quantity": 1,
"reason": "No longer wants"
}
],
"created_at": "2019-08-14T21:26:38+00:00"
}
}
}
}
Lot Create
This feature allows you to create a Lot. The mutation should be something like this:
mutation {
lot_create(
data: {
name: "Lot Nr.4"
sku: "1122334455"
expires_at: "2022-09-12"
is_active: true
}
) {
request_id
complexity
}
}
Lot Update
This feature allows you to update an existing Lot. The mutation should be something like this:
mutation {
lot_update(data: {
lot_id:"4651"
name:"Lot Nr.4"
expires_at:"2022-08-30"
is_active:true
}) {
request_id
complexity
}
}
Gotcha’s
In this section, we share tips on how to troubleshoot common errors about:
- Removing commas from tags
- Making Query Connections
- Client IDE not connecting
- Dates
- Dimensions
- Sell Ahead
- Order History
- Custom Options (Line Items)
- Country or State codes
Removing commas from tags
Tags in orders and products are expected in the following form:
tags:["tag1","tag2","tag3"]
Our system is set to remove commas from tag strings, so in the case of sending tags this way:
tags:["tag1,tag2,tag3"]
The order or product will end up having a tag that looks like:
tag1tag2tag3
Please review how tags are being sent, as this has the potential to make Automation Rules and Multi Warehouse Allocation Rules that are based on tags skip these orders.
Making query connections
For example, a query like the following:
query {
purchase_orders {
request_id
complexity
data {
edges {
node {
id
line_items {
edges {
node {
sku
}
}
}
}
}
}
}
}
Has a connection for line_items
inside purchase_ordes
, so this means that if we don’t specify line_items(first:10)
and purchase_orders(first:10)
the complexity would be of 10001 (100 purchase_orders
* 100 line_items each
+ 1 ), even if the PO does not have 100 line items or the response does not contain 100 purchase orders. To send the call you need enough credits to match the complexity, however, we reimburse the extra credits if the response has less objects than queried.
Client IDE not connecting
A common error you might be having when trying to view de Docs & Schema using any of our recomended Client IDEs is not being able to access the docs.
For this purpose, we have a couple of suggestions:
- Using the Desktop Versions or Extensions of this Client IDEs. Usually, Web versions of these clients tend to have this kind of issue.
- Disabling cache on the Client IDE*
*you can do this by opening dev tools from inside the Client IDE and selecting Disable cache
Dates
All dates are stored as UTC
ISODateTime: A DateTime field type that understand ISO 8601 strings, besides datetime objects. It supports strings with and without times, as well as using T or space as delimiter
Ex.
- YYYY-mm-dd
- YYYY-mm-dd HH:MM:SS
- YYYY-mm-ddTHH:MM:SS
Dimensions
Input dimensions are considered to be in the account’s settings unit, unless specified by the field name like weight_in_lbs
Output dimensions will always be in the account’s settings unit, unless specified by the field name like weight_in_lbs
Sell Ahead
The sell_ahead
field inside warehouse_products
has a default cost of 15.
The reason for this is that complex calculations are required to figure out the sell_ahead quantities, as we need to check into existing POs to fetch these values.
Order History
The order_history
connection inside order
has a default cost of 10.
This is because it returns every entry of the order history, no matter how many lines it has, without the need to paginate, as it is not an edge.
Custom options
The available field inside line_items, called custom_options should have the following format:
custom_options: {key1:"value1", key2:"value2"}
So for example if you are trying to create an order using this field with order_create
or order_add_line_items
, the line items section should look something like this:
line_items: [
{
partner_line_item_id: "TEST-EN-8550-1A"
sku: "3004022005228"
quantity: 1
price: "14.99"
product_name: "Test product name"
custom_options: {
key1: "foo",
key2: "bar",
key3: "baz"
}
}
]
However, if you use the order_update_line_items
mutation to update the custom_options
field, you need to type in all of the existing keys, not just those you need to update. The mutation clears all that exists in the field and pastes only what was sent in it.
For example, if you only want to update key3 in the above line item, you should send the following:
line_items: [
{
id: "4357356783"
custom_options: {
key1: "foo",
key2: "bar",
key3: "newvalue"
}
}
]
Country or State codes
On the order_create
mutation, for the shipping address you will see the following fields:
shipping_address: {
address1: "2326 Street Dr"
address2: ""
city: "Fort Collins"
company: ""
country: "US"
country_code: "US"
email: "EXAMPLE@GMAIL.COM"
first_name: "John"
last_name: "Johnson"
phone: "(970) 111-111"
state: "CO"
state_code: "CO"
zip: "80528"
}
Both country_code and state_code have been deprecated.
In order to create successfully the order, country has to be the valid country code, for example, “US”, and similar, the state has to be a valid state code such as “CO”