Flows
Returns

Returns

In this section, we will guide you through the process of managing returns using our GraphQL Public API.

To be able to do this we will go through the following steps:

  1. Get the order for which you would like to create a return
  2. Create the return
  3. Create an exchange order
  4. Use webhooks to receive return status changes
  5. Get the return information
  6. Update or complete a return

1. Get the order

First step you may need to take when managing returns is to get the order you would like to return.

To accomplish this, you can use both:

  • order query
  • orders query

Using the order query

For the orders query you must know the ShipHero order_id beforehand and it will only return that exact order.

For example:

query {
  order(id: "117384888") {
    request_id
    complexity
    data {
      id
      legacy_id
      order_number
      partner_order_id
      shop_name
      fulfillment_status
      order_date
      line_items(first: 5) {
        edges {
          node {
            id
            legacy_id
            sku
            partner_line_item_id
            quantity
            price
            product_name
            option_title
            fulfillment_status
            quantity_pending_fulfillment
            quantity_shipped
            warehouse
            quantity_allocated
            backorder_quantity
            custom_options
            custom_barcode
            eligible_for_return
            customs_value
            warehouse_id
            locked_to_warehouse_id
            subtotal
            barcode
            created_at
            updated_at
            order_id
          }
        }
      }
    }
  }
}

Using the orders query

As for the orders query, it will allow you to filter using more resources, such as:

  • shop_name: Is the name of the store were the order is from. For example: tomstomcats.myshopify.com
  • partner_order_id: If the order comes in from a store like Shopify, this should match the order_id from Shopify
  • order_number: As an alternative to order_id you can use order number with the orders query.
  • email: The email associated with the order (the client’s email).
  • updated_from ; updated_to: Based on last updates made on the order.
  • order_date_from ; order_date_to: Based on the order creation date in ShipHero.
  • customer_account_id: In case you are a 3PL and you need to filter by the Customer Account ID.

You could use any of them, and combine them as needed. Other available filters are warehouse_id and fulfillment_status.

2. Create the return

To generate a return you need to use the return_create mutation

mutation {
  return_create(
    data: {
      order_id: "117384888"
      warehouse_id: "6545"
      return_reason: "Too small"
      label_type: FREE
      label_cost: "0.00"
      display_issue_refund: true
      address: {
        name: "Customer Example"
        address1: "55 W RAILROAD AVE"
        address2: ""
        city: "GARNERVILLE"
        state: "NY"
        country: "US"
        zip: "10923-1261"
        phone: "55555555555"
      }
      dimensions: {
        height: "1.00"
        width: "1.00"
        length: "1.00"
        weight: "1.00"
      }
      shipping_carrier: "UPS"
      shipping_method: "Ground"
      line_items: {
        sku: "10044334339"
        quantity: 1
        return_reason: "Too small"
        condition: "Good"
      }
      tracking_number: "14322345667"
      create_label: false
      partner_id: "MO721"
    }
  ) {
    request_id
    complexity
    return {
      id
      legacy_id
    }
  }
}

3. Create an exchange order

To generate an exchange order, the mutation is similar to the one on 2, but this time exchange items section must be included inside the line items:

line_items: {
  sku: "10044334339"
  quantity: 1
  return_reason: "Too small"
  condition: "Good"
  exchange_items:{
    exchange_product_sku:"10044334339"
    quantity:1
  }
}

And if you also add the exchange information on the return query you should also be able to see the exchange order id that gets created for this return, something like this:

mutation {
  return_create(
    data: {
      order_id: "117384888"
      warehouse_id: "6545"
      return_reason: "Too small"
      label_type: FREE
      label_cost: "0.00"
      address: {
        name: "Customer Example"
        address1: "55 W RAILROAD AVE"
        address2: ""
        city: "GARNERVILLE"
        state: "NY"
        country: "US"
        zip: "10923-1261"
        phone: "55555555555"
      }
      dimensions: {
        height: "1.00"
        width: "1.00"
        length: "1.00"
        weight: "1.00"
      }
      shipping_carrier: "UPS"
      shipping_method: "Ground"
      line_items: {
        sku: "10044334339"
        quantity: 1
        return_reason: "Too small"
        condition: "Good"
        exchange_items:{
          exchange_product_sku:"10044334339"
          quantity:1
        }
      }
      tracking_number: "14322345667"
      create_label: false
      partner_id: "MO721"
    }
  ) {
    request_id
    complexity
    return {
      id
      legacy_id
      exchanges{
        exchange_order{
          id
          legacy_id
        }
      }
    }
  }
}

The response should contain the information on the order that got created for the exchange:

{
  "data": {
    "return_create": {
      "request_id": "5e7acbba92bfc0024421e71e",
      "complexity": 10,
      "return": {
        "id": "UmV0dXJuOjEwOTUyNTQ=",
        "legacy_id": 1095254,
        "exchanges": [
          {
            "exchange_order": {
              "id": "T3JkZXI6MTIwMTk3Mzgy",
              "legacy_id": 120197382
            }
          }
        ]
      }
    }
  }
}

4. Use webhooks to receive return status changes

The Return Update webhook allows you to receive notifications on a URL that you set up on your system. This webhook will be called anytime a return is created or updated.

To be able to configure the webhook you must first register to the webhook by using the webhook_create Mutation.

mutation {
  webhook_create(data: { 
    name: "Return Update", 
    url: "https://someValidURL.com/webhook" 
  }) {
    request_id
    complexity
    webhook {
      name
      url
    }
  }
}

Where:

  • name: Is the type of webhook you will be subscribing to, in this case, Return Update.
  • url: A valid URL for your webhook.

Once you are subscribed to the webhook, you should get notifications anytime a return is created or updated, and the data should look something like this:

{
    "status": "pending",
    "label_cost": "0.00",
    "order_id": 117384888,
    "return_id": 1095254,
    "partner_order_id": "MO721",
    "picked_up": false,
    "reason": "Too small",
    "label_type": "Free Label",
    "items": [
        {
            "sku": "10044334339",
            "partner_line_item_id": "MO721-282970272",
            "warehouse_id": 6545,
            "item_reason": "Good",
            "restock": 0,
            "id": 1772154,
            "quantity_received": 0,
            "quantity": 1
        }
    ],
    "created_at": "2020-03-25 03:10:51",
    "shop_name": "Manual Order",
    "tracking_number": "14322345667",
    "date_used": null,
    "test": "0",
    "order_number": "MO721"
}

5. Query a return

You might also need to get the return information by using a query. To achieve this you could use:

  • return query
  • returns query
  • return_exchange query

Using the return query

To use the return query you must know the return_id, and the query look like this:

query {
  return(id: "1095254") {
    request_id
    complexity
    data {
      id
      legacy_id
      account_id
      order_id
      partner_id
      reason
      status
      label_type
      label_cost
      cost_to_customer
      shipping_carrier
      shipping_method
      display_issue_refund
      dimensions {
        height
        length
        width
        weight
      }
      address {
        name
        address1
        address2
        state
        city
        zip
        country
        phone
      }
      line_items {
        id
        legacy_id
        account_id
        line_item_id
        warehouse_id
        product_id
        return_id
        quantity
        condition
        is_component
        type
        reason
        created_at
        updated_at
        line_item {
          id
          legacy_id
          sku
          partner_line_item_id
          quantity
          price
          product_name
          option_title
          fulfillment_status
          quantity_pending_fulfillment
          quantity_shipped
          warehouse
          quantity_allocated
          backorder_quantity
          custom_options
          custom_barcode
          eligible_for_return
          customs_value
          warehouse_id
          locked_to_warehouse_id
          subtotal
          barcode
          created_at
          updated_at
        }
      }
      created_at
    }
  }
}

Using the returns query

For the returns query you can use the following filters:

  • order_id: Using the ShipHero order_id this filter allows you to get all the returns created for a specific order
  • warehouse_id: This filter allows you to see all the returns created for a specific warehouse
  • date_from ; date_to: Based on the date the returns were created
  • customer_account_id: In case you are a 3PL and would like to know all the returns created for a specific customer account

For example:

query {
  returns(
    warehouse_id: "V2FyZWhvdXNlOjgwNzU="
    date_from: "2020-03-10"
    date_to: "2020-03-11"
  ) {
    request_id
    complexity
    data(first: 1) {
      edges {
        node {
          id
          legacy_id
          account_id
          order_id
          partner_id
          reason
          status
          label_type
          label_cost
          cost_to_customer
          shipping_carrier
          shipping_method
          display_issue_refund
          line_items {
            id
            legacy_id
            account_id
            line_item_id
            warehouse_id
            product_id
            return_id
            quantity
            condition
            is_component
            type
            reason
            created_at
            updated_at
            line_item {
              id
              legacy_id
              sku
              partner_line_item_id
              quantity
              price
              product_name
              option_title
              fulfillment_status
              quantity_pending_fulfillment
              quantity_shipped
              warehouse
              quantity_allocated
              backorder_quantity
              custom_options
              custom_barcode
              eligible_for_return
              customs_value
              warehouse_id
              locked_to_warehouse_id
              subtotal
              barcode
              created_at
              updated_at
            }
          }
          created_at
        }
      }
    }
  }
}

Using the return_exchange query

For the returns that have an exchange, you can use a specific query that might get as complex as you need, for example:

query {
  return_exchange(id: "1095253") {
    request_id
    complexity
    data {
      id
      legacy_id
      exchange_order_id
      return_id
      account_id
      exchange_order {
        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
        gift_note
        packing_note
        required_ship_date
        tags
        line_items(first: 1) {
          edges {
            node {
              id
              legacy_id
              sku
              partner_line_item_id
              quantity
              price
              product_name
              option_title
              fulfillment_status
              quantity_pending_fulfillment
              quantity_shipped
              warehouse
              quantity_allocated
              backorder_quantity
              custom_options
              custom_barcode
              eligible_for_return
              customs_value
              warehouse_id
              locked_to_warehouse_id
              subtotal
              barcode
              created_at
              updated_at
              order_id
            }
          }
        }
        authorizations {
          transaction_id
          authorized_amount
          postauthed_amount
          refunded_amount
          card_type
          date
        }
        holds {
          fraud_hold
          address_hold
          shipping_method_hold
          operator_hold
          payment_hold
        }
        shipments {
          id
          legacy_id
          order_id
          user_id
          warehouse_id
          pending_shipment_id
          address {
            name
            address1
            city
            state
            zip
            country
            phone
          }
          picked_up
          needs_refund
          refunded
          delivered
          shipped_off_shiphero
          dropshipment
          created_date
          line_items(first: 1) {
            edges {
              node {
                id
                legacy_id
                line_item_id
                shipment_id
                shipping_label_id
                quantity
                line_item {
                  sku
                  id
                }
              }
            }
          }
        }
        flagged
        saturday_delivery
        ignore_address_validation_errors
        priority_flag
        allocation_priority
      }
      exchange_items {
        id
        legacy_id
        return_item_id
        sku
        quantity
      }
      original_return {
        id
        legacy_id
        account_id
        order_id
      }
    }
  }
}

Where the id is the return_id.

6. Update or complete a return

Only status can be updated of modified on existing returns. And an example of the mutation available is the following:

mutation{
  return_update_status(data:{
    return_id:"1095254"
    status:"complete"
  }){
    request_id
    complexity
    return{
      id
      status
    }
  }
}

Note

Stock cannot be received using a mutation. The warehouse should receive stock in ShipHero so that the location where the item is put is correct.

Below are the default statuses of a return in ShipHero and what they are used for or will trigger:

Pending – does not trigger anything but is used to note that a return is in progress.

Warehouse Complete – does not trigger anything by default and is used to flag a return that has made its way through warehouse processing.

Complete – triggers a refund for the return and used when the return has made its way through your processes.

InventoryOrder Fulfillment