Developer Resources > 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:
First step you may need to take when managing returns is to get the order you would like to return.
To acomplish this, you can use both:
orderqueryordersquery
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.compartner_order_id: If the order comes in from a store like Shopify, this should match the order_id from Shopifyorder_number: As an alternative to order_id you can use order number with the orders query.email: The email asociated 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
}
}
}
Were:
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 migh also need to get the return information by using a query. To achieve this you could use:
returnqueryreturnsqueryreturn_exchangequery
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 ShipHeroorder_idthis filter allows you to get all the returns created for a specific orderwarehouse_id: This filter allows you to see all the returns created for a specific warehousedate_from;date_to: Based on the date the returns were createdcustomer_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.