Developer Resources > Examples

Examples

 

In this section, we will explore some examples of the different queries & mutations available on the API.

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 Schema.

Queries:

Mutations:

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.

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,
        }
    }
  }
}

Notes:

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