Examples

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

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
  • email
  • 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

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

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:

  1. Using the Desktop Versions or Extensions of this Client IDEs. Usually, Web versions of these clients tend to have this kind of issue.
  2. Disabling cache on the Client IDE*

*you can do this by opening dev tools from inside the Client IDE and selecting Disable cache

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”