How to use the advanced refunds flow

What you’ll learn

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

• Key concepts and terms
• The difference between the original and advanced flows
• 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.

Original Vs. Advanced Flows

Both the original and advanced workflows follow the same high-level process, as outlined below:

• Create: The creation of the Return or Cancellation Request
• Return: Process the request (e.g. mark items as having been returned)
• Refund: Finalize the refund

Some other points to note:

• You can see which roles (Seller or Operator) can perform each step using the GraphQL API
• We have omitted the Deny & Revert steps in the above example for brevity

Expanding this example for the original and advanced workflows, you will observe some differences:

Original Workflow

Some points to note on the original workflow:

• When using the GraphQL API the same flow is used for both Cancellations and Returns
  • I.e. The Cancellation step (where items have not yet been dispatched) still requires that you mark items as “Returned”
• Only the Operator can deny the refund request
• In the case of a Return, there is no way to determine that the product does not need to be returned
  • E.g. If the return was for a perishable food item, it is unlikely you’d want that back

Advanced Workflow

Some points to note on the advanced workflow:

• The “Return” step is now split into 2 “optional” steps: “Return” & “Accept”
• For Cancellation flows, you can now omit the need to mark items as returned (Return and Accept steps), and move straight to approving (Refund)
• For Returns you can choose whether you:
  • Require the item to be returned (Return)
  • Do not require the item to be returned (Accept)
• Sellers can now “Deny” refund requests at a line item level (depending on where they are in request cycle)

We’ll go through a more detailed worked example later in this article, but to summarize the main benefits of the advanced workflow over the original:

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 Seller and Operator can decide whether products need to be returned (or not)
3. The Cancellation flow is is streamlined

Common Use Cases

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

Using the advanced workflow, we are going to cover the following uses cases:

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

Before running through the use-cases, let’s take a quick look at the mutations we are going to be using.

GraphQL Mutations

With the new workflow, we have added some new mutations, and updated some existing ones, we have summarized these below:

Creation Statuses

As mentioned above, the refundRequestCreate mutation has been updated to accept 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

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: "Item Returned OK" }]
    }
  ) {
    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: "Do not need item to be returned" }]
    }
  ) {
    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
    }
  }
}