Context

We’re looking for a future-proof, merchant-obsessed, and scalable way to integrate Bigblue with external returns solutions (the Solution in the rest of the doc).

High-level requirements

1. [Solution → Bigblue] New return notification

The Solution notifies Bigblue of a new return coming our way.

1b. [Solution → Bigblue] New return notification for orders not initially fulfilled by Bigblue

This will happen a lot for onboarding merchants redirecting returns to our warehouse.

2. [Bigblue → Solution] Quality control result

Bigblue notifies the Solution that the inspection is complete and forwards the results.

Other P2 requirements

Bigblue shipping labels

Use our TMS or other ways to get a shipping label from our accounts. This won’t always be the case because some returns solutions cover more use cases and geographies than we can offer.

Solution

There are three possible approaches:

1. A custom integration with the Solution using their APIs,
2. Extending Bigblue’s APIs to allow the Solution to integrate with Bigblue,
3. [Preferred] Using Shopify as a communication channel.

Integrating through Shopify

The main advantages of this approach are that 1) we have a common identifier for everything that we already understand (the Shopify identifiers), 2) it’s not partner-dependent for both the Solution and Bigblue, and 3) we want to build that integration anyways.

New return notification

1. When a new return is expected, the Solution creates a new Return using the returnCreate mutation. This will automatically create a reverse fulfillment order (see below).

A reverse fulfillment order is a group of one or more items in a return that will be processed by a merchant or a third-party fulfillment service. Creating a return or approving a return creates a reverse fulfillment order. There can be more than one reverse fulfillment order for a return at a given location.

• Return creation required fields

1. Whoever (Bigblue or the Solution) generates the reverse delivery label creates a ReverseDelivery using the reverseDeliveryCreateWithShipping mutation, adding the tracking number, carrier, and tracking label URL.

2. Bigblue listens to REVERSE_DELIVERIES_ATTACH_DELIVERABLE webhook events (payload reference) and creates the return in our system.

   • Bigblue return creation field mapping

   Limits:

   1. The only limit of this solution is customer-managed delivery. In that case, we cannot identify the parcel at the warehouse, and the Solution does not have a deliverable to communicate. We could use a dummy number.
   2. If Bigblue generates the shipping label, it must listen to returns/approve events instead.

3. Bigblue declares the expected return to our WMS.

<aside> 💡 Return shipments are identified at the warehouse using the carrier tracking number. External solutions also add an identifier they generate; as an MVP, we don’t do anything about it.

</aside>

Quality control result

1. When a Bigblue warehouse identifies and inspects a return, Bigblue calls the reverseFulfillmentOrderDispose mutation. That adds Dispositions to the ReverseFulfillmentOrderLineItems. The disposition type is MISSING for missing items, NOT_RESTOCKED for damaged items, and RESTOCKED for OK items.

2. The Solution subscribes to the reverse_fulfillment_orders/dispose webhook events and uses them as a trigger for the rest of the flow, including merchant approval or refunds.

Reference code

• JS code used to validate the use case

Resources

Manage reverse fulfillment orders

Manage reverse deliveries

Manage returns