Skip to main content

​
Overview

E-commerce merchants typically manage returns through their primary platforms like Shopify, BigCommerce, or WooCommerce, but return requests often originate from multiple touchpoints—customer service interactions, social media complaints, marketplace disputes, or direct customer emails. For ISVs building commerce-enabled platforms, this creates a critical operational challenge: your customers must be able to process and track returns seamlessly across all channels while maintaining accurate inventory levels and customer satisfaction. This documentation covers how to capture return requests from your platform and enable customers to automatically sync return data to their preferred return management systems – like Loop Returns – and e-commerce platforms, ensuring consistent inventory updates, refund processing, and customer communication regardless of where the return was initiated.
Have you read our Blueprint on creating and managing orders?

If not, we highly recommend you give it a read before continuing here. Returns and orders are inherently intertwined and, sometimes, directly reference each other. It’s important you get a good sense of the typical structure of an order and how workflows are built to manage them.

​
Components of Returns

​
Core Components

  • Return Information: Return ID, date, and status
  • Original Order Reference: Link to the original purchase order
  • Items & Quantities: What products are being returned and how many
  • Return Reason: Why the customer is returning the items

​
Secondary Components

  • Refund Details: Amount to refund and payment method
  • Return Shipping: How items will be sent back and tracking
  • Condition Assessment: Product state upon return
  • Metadata: Timestamps, notes, and processing rules

​
Returns vs. Refunds

Returns and refunds are closely related but represent two distinct parts of the post-purchase flow. Most e-commerce platforms, including Shopify, WooCommerce, and BigCommerce, treat them as separate entities and often expose them through different APIs or workflows. A return is a logistical process focused on the movement and condition of physical goods. It determines where an item is sent back, how it’s received, and whether it should be restocked at a particular fulfillment location. Merchants typically only manage returns directly if they control the fulfillment or inventory being updated. A refund is a financial process concerned with reversing some or all of the original payment. It specifies how much money should be returned to the customer and through which payment method or gateway. Refunds are about adjusting the financial record of the order, independent of what happens to the physical item.

​
Partial Returns & Refunds

Partial returns and partial refunds introduce additional nuance because only a portion of the original order is being reversed. A partial return occurs when the customer sends back only some of the items or only part of a bundled product. The logistical considerations remain the same—determining where the items go, updating inventory counts, and handling any condition-based decisions—but applied selectively to specific line items or quantities rather than the entire order. A partial refund addresses the financial side when only part of the order’s value should be credited back to the customer. This may correspond to a partial return, but doesn’t have to: merchants can issue a partial refund without receiving goods back (for example, to compensate for damage, delays, or missing components). Partial refunds also require specifying the exact amount and the payment method to be credited, and often involve prorating taxes, shipping, or discounts depending on platform rules. Together, partial returns and partial refunds add flexibility but also require merchants to treat the physical and financial processes independently, ensuring that each reflects the correct subset of the original order.

​
Building Your First Integration

Select the appropriate drop-down below based on which Alloy Automation product you’ll be building with.

​
1. Choose an E-Commerce Platform to Integrate With

Popular e-commerce platforms include Shopify, WooCommerce, BigCommerce, and Shopline. Most of these platforms handle order placement very similarly so you’lld find a lot of the steps covered here fairly universal

​
2. Choose a Workflow Trigger

Here, we’ll assume that the returns are originating in your platform, as the ISV, or a platform that you manage on behalf of your customers. You can either send return/refund events in real-time or run a recurring sync based on your needs. Those options are listed below:
  • Custom Event - Invoked in your systems and can be used to pass along order data as individual orders are created
  • Recurring Sync - Can be used to run the order syncing workflow on a recurring basis, should also be combined with a polling endpoint from which the workflow can pull bulk orders via Custom API Call

​
3. Send Refund/Return Data to Alloy

Unlike orders, returns and refunds may not exist as standlone records, but, instead, as status updates within existing order records in your system. First thing’s first, you need to identify how you store and process returns in your system and how you want to communicate that to Alloy. As covered in the previous step, you can do so through a custom event or polling trigger. However, Alloy receives the data from your systems, make sure the payload is clear about_which specific items are being returned, especially if you support partial refunds_When building your return payload schema, you can reference the example payload below, which contains the typical fields and values that most e-commerce platforms require.
{
  "orderId": "ORD-2025-001234",
  "orderNumber": "1234",
  "orderDate": "2025-01-15T14:30:00Z",
  "status": "confirmed",
  "customer": {
    "id": "CUST-456789",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+1-555-0123"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "company": "Acme Corp",
    "address1": "123 Main Street",
    "address2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "US",
    "phone": "+1-555-0123"
  },
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "company": "Acme Corp",
    "address1": "456 Business Ave",
    "address2": "",
    "city": "Brooklyn",
    "state": "NY",
    "zipCode": "11201",
    "country": "US",
    "phone": "+1-555-0124"
  },
  "lineItems": [
    {
      "id": "LINE-001",
      "productId": "PROD-789",
      "sku": "TEE-BLK-M",
      "title": "Black T-Shirt",
      "variant": "Medium",
      "quantity": 2,
      "price": 29.99,
      "totalPrice": 59.98
    },
    {
      "id": "LINE-002",
      "productId": "PROD-456",
      "sku": "HAT-RED-OS",
      "title": "Red Baseball Cap",
      "variant": "One Size",
      "quantity": 1,
      "price": 24.99,
      "totalPrice": 24.99
    }
  ],
  "pricing": {
    "subtotal": 84.97,
    "tax": 7.65,
    "shipping": 9.99,
    "discount": 5.00,
    "total": 97.61,
    "currency": "USD"
  },
  "shipping": {
    "method": "Standard Ground",
    "carrier": "UPS",
    "trackingNumber": "1Z999AA1234567890",
    "estimatedDelivery": "2025-01-20"
  },
  "payment": {
    "method": "credit_card",
    "status": "paid",
    "transactionId": "TXN-987654321",
    "gateway": "stripe"
  },
  "notes": "Please leave at front door",
  "tags": ["online", "first-time-customer"],
  "createdAt": "2025-01-15T14:30:00Z",
  "updatedAt": "2025-01-15T14:45:00Z"
}

​
4. Associate the Return with an Existing Order

If the return payload from your systems contains the internal ID of your e-commerce platform of choice then you can simply use that ID when creating the refund and/or return via the e-commerce platform’s connector action in Alloy. If that’s not available, you may need to lookup the order based on other information.
Depending on which e-commerce platform you use, associating a return with an existing Order ID may be the only required step in order to successfully process the return and refund. This generally means that full refunds and returns easier than their partial counterparts

​
5. Refund the Order

At the very least you will want to handle the refunding of the order even if you’re_not_  handling the return logistics. To do so, you can choose the relevant action – our e-commerce connectors usually have actions likeCreate a Refund  – and pass in all necessary order information.If you are supporting partial refunds you will also need to pass in individual line items. The e-commerce connector platform your using will automatically calculate the delta between the items original purchased and those returned so that only a partial refund is calculated.
Generally, you won’t need to worry about handling the refund transaction itself, that being the actual refunding of the money to the customer’s chosen payment method. All you need to do is tell the e-commerce connector which items need to be returned and the e-commerce platform will take care of fulfilling the refund via the customer’s payment method.

​
5A. Handle the Return (Optional)

Handling the return of an item can vary wildly depending on the e-commerce connector you’re working with. Let’s take Shopify as an example:with Shopify, you have the option of using the REST API (Admin API) or newer GraphQL API. If using the Admin API you would_not_  treat the return as a separate action and would, instead, you would selectReturn  as the ‘Restock Type’ and enter a location ID for the fulfillment location where the item will be restocked (see the image below for details).Screenshot 2025-11-07 at 11.10.26 AM.pngIn Shopify’s GraphQL API, however, the return itself is a separate API request. You can see an example of that request below:
mutation CreateReturn($input: ReturnCreateInput!) {
  returnCreate(return: $input) {
    return {
      id
      status
      returnLineItems {
        id
        quantity
      }
    }
    userErrors {
      field
      message
    }
  }
}

​
6. Communicate the Refund to the Customer (Optional)

While optional, we highly recommend you communicate all refunds and returns to customers.
This is the final and easiest step: informing the customer of the completed refund and return. Most e-commerce platforms have built-in email tools and you just need to toggle a flag on the connector action in Alloy that tells the e-commerce platform to email the customer when the refund is complete. In the screenshot below you can see how notifying the customer is a simple toggle within theCreate refund action on Alloy’s Shopify connector.Screenshot 2025-11-07 at 11.20.55 AM.png