How to use the refunds flow

What you’ll learn

In this how to we take you through how to perform cancellations and returns using the refund workflow, specifically:

• Key concepts and terms
• Processes and scenarios for common cancellation and return use cases
• The GraphQL API calls you’ll need to make

Key Terms

Before launching into the processes that can be followed, it’s worth clarifying the language and terms used when we talk about refunds and returns.

Workflow overview

The refunds flow is depicted below:

Happy path

• Create: The creation of the Return or Cancellation Request
• Return (optional): Requires that items that have been dispatched, need to be returned to the seller
• Accept (optional): Can be used:
  • When items are required to be returned - accept that they have been successfully
  • When items are not required to be returned - accept that refund is ok to progress to the next step
• Refund: Finalize the refund

Unhappy path

• Deny (optional): Can be used in multiple scenarios:
  • Operator or Seller rejects the creation of a Refund Request
  • Operator of Seller rejects the return step of a Refund Request
  • Operator rejects the acceptance step of a Refund Request
• Deny (optional): Operator chooses to revert an approved Refund Request

Key takeaways

1. Refunds can be processed individually at the Line Item Level (as opposed processing an entire request that may contain many line items)
2. The flow is flexible in terms of how it is executed, so can be tailored for different paths and scenarios (discussed below)

Common Use Cases

To further illustrate how the refund workflow can be used, we’ll run through a number of common scenarios.

All use cases will start with the same base condition(s):

• An Order has successfully been created with 1 line item
• For the Return scenarios, the line item will have been dispatched

GraphQL Mutations

The GraphQL mutations we’ll be working with are summarized below:

Creation Statuses

As mentioned above, the refundRequestCreate mutation accepts a status for each line item that is added to the request, an example of this mutation is shown below:

mutation {
  refundRequestCreate(
    input: {
      invoiceId: "SW52b2ljZS0xMDAxOA=="
      lineItems: [
        {
          lineItemId: "TGluZUl0ZW0tMTk="
          quantity: 1
          reason: "Milk has gone sour"
          status: PENDING_APPROVAL
        }
      ]
      notes: [{ note: "Do not require item return" }]
    }
  ) {
    errors {
      field
      messages
    }
    refundRequest {
      id
      status
    }
  }
}

Here you can see this request adds 1 line item to the request with a status of PENDING_APPROVAL, this means that the Seller will need to determine how they want to process the request, this could be either:

• Just accept the request (refundRequestLineItemAccept)
• Require that the items are returned (refundRequestLineItemReturn + refundRequestLineItemAccept)

The takeaway point is that this status determines next available steps in the overall workflow, you would select a different status depending on how you wanted the request to be processed. The complete list of statuses you can supply here are:

Use Case Examples

Pulling this information together, you can observe the mutation calls you’d need to make to cover all our scenarios, noting that we have abbreviated the full mutation name for a simpler label as follows:

Note: Be sure to pay attention to status used with each call to Create (refundRequestCreate).

State Transitions

Before we move on to a worked example, the last concept that you should be aware of are the various states that each of the primary objects participating in the refund request can take. Those objects are:

A simple example of the relationship between these objects is shown below:

All of the objects above have state, and in our worked example we’ll provide state transitions for all of them, however for the moment we’ll focus in on the states that the following objects can have:

• RefundRequest
• RefundRequestLineItem

RefundRequest States

The RefundRequest object can have the following states:

RefundRequestLineItem States

The RefundRequestLineItem object can have the following states:

RefundRequest & RefundRequestLineItem State Correlation

The matrix below shows the correlation between RefundRequest and RefundRequestLineItem states:

Worked Example

The following worked example follows Scenario 5 which utilizes all of the new and updated mutations. You should be able to take this example and adapt it easily to the remaining 5 uses-cases.

As a reminder, Scenario 5 is as follows:

Before we start

As this is a return scenario the following pre-conditions need to be met before we can begin with the refund flow:

• You will need a created order with 1 line item.
  • For more information on creating orders in GraphQL refer to this article
• The line item on the order / invoice has been dispatched
  • You can use the shipmentCreate GraphQL mutation to achieve this or just dispatch the line item from the Seller Portal

At this point our primary objects should have the following state:

We’ll additionally track the webhook events for the following webhook types as we move through out example:

• Refund Request
• Refund Request Line Item

Step 1: Call refundRequestCreate

The first step is to call refundRequestCreate, for this you will require:

1. The Invoice Id
2. The LineItem Id of the Line Item you want to return
3. The Line Item status we want to use in this case this will be: PENDING_APPROVAL

This call can be made by:

• The Operator
• The Seller (requires additional permissions)

An example mutation call is shown below:

mutation {
  refundRequestCreate(
    input: {
      invoiceId: "SW52b2ljZS0xMDAxOA=="
      lineItems: [
        {
          lineItemId: "TGluZUl0ZW0tMTk="
          quantity: 1
          reason: "Cracked Screen"
          status: PENDING_APPROVAL
        }
      ]
      notes: [{ note: "High value item, requires return" }]
    }
  ) {
    errors {
      field
      messages
    }
    refundRequest {
      id
      status
      lineItems {
        id
        status
      }
    }
  }
}

A successful call will result in the following:

• RefundRequest Id
• RefundRequestLineItem Id (we’ll need this for the next step)

Our primary objects should have the following state:

The following webhook events will fire:

Step 2 Call refundRequestLineItemReturn

The Seller in this case takes the decision that they want the line item returned, so they will make a call to refundRequestLineItemReturn, to do so they will need the RefundRequestLineItem Id of the Line Item you want to return

This call can be made by:

• The Operator
• The Seller

An example mutation call is shown below:

mutation {
  refundRequestLineItemReturn(
    input: {
      refundRequestLineItemId: "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTE2"
      notes: [{ note: "Confirm the return of this item is required" }]
    }
  ) {
    refundRequestLineItem {
      status
    }
    errors {
      field
      messages
    }
  }
}

Following a successful call, our primary objects should have the following state:

The following webhook events will fire:

Step 2a [Optional] Call returnShipmentCreate

The seller can optionally create a return shipment that can including tracking details, attachments etc. To use returnShipmentCreate you will need to pass the refundRequestId. This call can be made by:

• The Operator
• The Seller

An example mutation call is shown below:

mutation {
  returnShipmentCreate(
    input: {
      refundRequestId: "UmVmdW5kUmVxdWVzdC0yMA=="
      carrierId: "U2hpcG1lbnRDYXJyaWVyLTQ="
      trackingNumber: "ABC-1236"
      shippedItems: [
        { 
          lineItemId: "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTIw", 
          quantity: 1 
        }
      ]
    }
  ) {
   shipment {
      id
    }
    errors {
      field
       messages
    }
  }
}

Following a successful call, the statuses of our primary objects do not change:

No events for the webhooks we are monitoring will fire either:

Step 3 Call refundRequestLineItemAccept

The Seller will now wait until the item has been returned, once it has been and it fulfils the return criteria of the Seller, they would then call refundRequestLineItemAccept, to do so they will need:

1. The RefundRequestLineItem Id of the Line Item that has been returned

This call can be made by:

• The Operator
• The Seller

An example mutation call is shown below:

mutation {
  refundRequestLineItemAccept(
    input: {
      refundRequestLineItemId: "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTE3"
      notes: [{ note: "Item has been returned in a satisfactory condition" }]
    }
  ) {
    refundRequestLineItem {
      status
    }
    errors {
      field
      messages
    }
  }
}

Following a successful call, our primary objects should have the following state:

The following webhook events will fire:

Step 4 Call refundRequestRefund

With all of the Sellers steps completed, the Operator now has to finalize the refund by calling refundRequestRefund, to do so they need to supply:

1. The RefundRequestId Id of the refund request

This call can be made by:

• The Operator

An example mutation call is shown below:

mutation {
  refundRequestRefund(
    input: {
      refundRequestId: "UmVmdW5kUmVxdWVzdC0xNw=="
      notes: [{ note: "Refund Approved" }]
    }
  ) {
    errors {
      field
      messages
    }
    refundRequest {
      id
      status
    }
  }
}

Following a successful call, our primary objects should have the following state:

The following webhook events will fire:

Step 4a Call refundRequestApprove

It is assumed that you have followed all the example steps up to and including Step 3 above, with that being the case, the Operator can finalize the refund by calling refundRequestApprove in one of the following 2 ways.

Option 1 - Simplex

This is essentially an identical approach to that used with refundRequestRefund as shown below:

mutation {
  refundRequestApprove(input: 
    {
      refundRequestId: "UmVmdW5kUmVxdWVzdC0xNw=="
    }
  ) {
      refundRequest{
        id
        status
    }
    errors {
      field 
      messages
    }
  }
}

Calling this mutation will result in the same outcome you would have with calling refundRequestRefund.

Option 2 - Granular

The entire value-proposition of refundRequestApprove is to allow the caller to specify granular values for:

• lineItemAmount - The amount to be refunded to the shopper
• commissionAmount - The commission component of the lineItemAmount
• remittanceAmount - The remittance component of the lineItemAmount

You can also optionally specify the tax component of each if required. An example of this approach to calling refundRequestApprove is shown below:

mutation {
  refundRequestApprove(input: 
    {
      refundRequestId: "UmVmdW5kUmVxdWVzdC0xMDk="
      lineItemPriceBreakdowns: [
        {
          id: "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTE0OQ=="
          lineItemAmount: 1000
          commissionAmount: 200
          remittanceAmount: 800
        }
      ]
    })
  {
    refundRequest{
      id
      status
    }
    errors{
      field 
      messages
    }
  }
}