API Reference

Returns webhook events

Guide to integrating with ReturnBear's returns webhook events

ReturnBear's platform emits a variety of events related to returning items. Below is a detailed description of each event type.

Return Events

Event Types Overview

ReturnBear's webhook system emits events that follow a return item's lifecycle from initiation to completion. Each event contains detailed information about the return case, including customer details, item details, tracking, and verification status.

Event Payload Structure

All return events share a common payload structure containing ReturnCase model properties:

{
    "data": {
        // Customer contact information who initiated the return
        "customer_contact": {
            "email": "[email protected]",
            "language": "en-us",
            "name": "John Smith"
        },
        // External order reference generated by e-commerce platform (i.e. Shopify in most cases)
        "external_order_reference": {
            "id": "5267529334941",
            "number": "#5527"
        },
        // Fees associated with the return
        "fees": [
            {
                "category": "bonus",
                "fee": {
                    "amount": "10.00",
                    "currency": "CAD"
                },
                "name": "Bonus Store Credit"
            }
        ],
        // Items that are being returned
        "return_case_items": [
            {
                // External order line item reference generated by e-commerce platform (i.e. Shopify in most cases)
                "external_order_line_item_reference": {
                    "id": 12616291811485,
                    "gid": "gid://shopify/LineItem/12616291811485"
                },
                "fees": [],
                "price": {
                    "amount": 318,
                    "currency": "CAD"
                },
                // Product variant that is being returned
                "product_variant": {
                    "attributes": {
                        "color": "Dark Heathered Grey",
                        "size": "Medium"
                    },
                    "external_product_variant_reference": {
                        "id": 45725795877021,
                        "gid": "gid://shopify/ProductVariant/45725795877021"
                    },
                    // Product variant ID
                    "id": "01J33AZMFF2JK9GEY401549252",
                    // Product variant name
                    "name": "The Unblazer - M / Dark Heathered Grey",
                    // Product variant SKU
                    "sku": "1242342343249",
                    // Product variant UPC
                    "upc": ""
                },
                // Decision on whether to remit the item based on verification and merchant input, one of [PENDING, REMIT, DO_NOT_REMIT]
                "remittance_decision": "REMIT",
                // Method of return
                "return_method": "STORE_CREDIT",
                // Reason for return
                "return_reason": "UNMET_EXPECTATIONS",
                // Status of the return case
                "status": "APPROVED",
                // Unique identifier generated by ReturnBear for the return case item
                "uid": "f9de723f-3314-4a22-8cad-7e801ffafea6",
                // Verification Summary
                "verification_summary": {
                  // Any photos taken of the item for verification purposes
                  "photos": [
                    "https://example.com/photo.jpg"
                    ],
                  // The verified condition of the item, one of [ITEM_LIKE_NEW, ITEM_NOT_RECEIVED, ITEM_DAMAGED]
                  "verification_result": "ITEM_LIKE_NEW"
                }
            }
        ],
        // Method of return by customer
        "return_method": {
            "location": {
                "address": "527 Bloor St W, Toronto, ON M5S 1Y5, Canada",
                "name": "PenguinPickUp - Annex"
            },
            "method": "DROP_OFF"
        },
        // RMA number
        "rma_number": "7000549297",
        // Shortened unique identifier generated by ReturnBear for the return case
        "short_uid": "69EXP5",
        // Status of the return case
        "status": "APPROVED",
        // Store ID
        "store_id": 7,
        // History of tracking events which outline the return case's physical movement through the return process
        "tracking_events": [
          {
            "occurred_at": "2024-07-17T18:00:00Z",
            "origin_location": {
              "city": "Toronto",
              "country_code": "CA",
              "postal_code": "M5V 2H1",
              "name": "Customer Location"
            },
            "status": "APPROVED"
          },
          {
            "occurred_at": "2024-07-18T12:00:00Z",
            "origin_location": {
              "city": "Toronto",
              "country_code": "CA",
              "postal_code": "M5S 1Y5",
              "name": "PenguinPickUp - Annex"
            },
            "status": "RECEIVED_AT_RETURN_POINT"
          },
          {
            "occurred_at": "2024-07-18T14:00:00Z",
            "origin_location": {
              "city": "Toronto",
              "country_code": "CA",
              "postal_code": "M5S 1Y5",
              "name": "PenguinPickUp - Annex"
            },
            "status": "IN_TRANSIT_TO_HUB"
          },
          {
            "occurred_at": "2024-07-18T16:00:00Z",
            "origin_location": {
              "city": "Mississauga",
              "country_code": "CA",
              "postal_code": "L5T 1C1",
              "name": "ReturnBear Hub"
            },
            "status": "RECEIVED_AT_HUB"
          }
        ],
        // Tracking status of the return case
        "tracking_status": "RECEIVED_AT_HUB",
        // Unique identifier generated by ReturnBear for the return case
        "uid": "e72b1e7a-9e65-459f-bce9-d32ce2682e30",
        // Items received that were not originally approved for the return case
        "undeclared_items": [
          {
            // ReturnBear reference id of the undeclared item
            "id": "01JWC13W1P78H79SS867XNEEYN",
            // Verification summary of the item
            "verification_summary": {
              // Any photos taken of the item for verification purposes
              "photos": [
                "https://example.com/photo.jpg"
                ],
              // The verified condition of the item, one of [ITEM_LIKE_NEW, ITEM_DAMAGED]
              "verification_result": "ITEM_DAMAGED"
            }
          }
        ],
        // Status of the return case verification
        "verification_status": "PASSED",
    },
    "event_type": "RETURN_APPROVED",
    "happened_at": "2024-07-18T20:21:52.155182Z"
}

Detailed Event Types

The following events are triggered when a return case is created, updated, or completed. As a partner, you have the ability to subscribe to specific events to receive updates on the return case's status. To subscribe to events, reach out to [email protected] or on the shared ReturnBear Slack channel.

Initial Return Events

return/requested

  • Description: Triggered when a customer submits a new return request
  • Common Use Case: Initialize return tracking in your system
  • Key Fields to Monitor:
    • status: Will be "NEW"
    • rma_number: Unique return identifier

return/approved

  • Description: Triggered when a return request meets the return policy criteria and is approved
  • Common Use Case: Update order management system with approved return
  • Key Fields to Monitor:
    • status: Will be "APPROVED"
    • return_method: Contains chosen return method details

return/denied

  • Description: Triggered when a return request is rejected
  • Trigger Conditions:
    • Return policy violations
    • Automated or manual review failure
  • Key Fields to Monitor:
    • status: Will be "DENIED"

return/cancelled

  • Description: Triggered when a return request is cancelled
  • Trigger Conditions:
    • Customer cancellation
    • Administrative cancellation
  • Key Fields to Monitor:
    • status: Will be "CANCELLED"

Tracking Events

return/tracking_status_updated

  • Description: Triggered as the returned items(s) moves through the return network
  • Status Progression:
    1. APPROVED: Returned item(s) has been approved and is awaiting drop-off at a return verification or courier location for shipment to a ReturnBear hub
    2. RECEIVED_AT_RETURN_POINT: Returned item(s) dropped off at dedicated return verification location
    3. IN_TRANSIT_TO_HUB: Returned item(s) in transit to a ReturnBear hub
    4. RECEIVED_AT_HUB: Returned item(s) arrived at ReturnBear hub
  • Key Fields to Monitor:
    • tracking_status: Current status
    • tracking_events: Historical timeline of status changes

Verification Events

return/verification_passed 🟢

  • Description: Triggered when returned item(s) pass verification criteria
  • Significance: Critical trigger for payment processing systems
  • Integration Note: Use this event to trigger customer refunds, exchanges, store credit or gift card issuance
  • Key Fields to Monitor:
    • verification_status: Will be "PASSED"
    • return_case_items[*].verification_summary.verification_result: will be "ITEM_LIKE_NEW" for all return case items
    • return_case_items[*].remittance_decision: will be "REMIT" for all return case items
    • undeclared_items: may or may not be populated with additional verified items included in the physical return that were not declared in the original approved return case. If populated, these items may require manual review or customer communication. Note that the presence of undeclared items does not influence the overall return case verification status.
    • Note on verification_result values:
      • For return_case_items: possible values are ITEM_LIKE_NEW, ITEM_NOT_RECEIVED, or ITEM_DAMAGED
      • For undeclared_items: possible values are only ITEM_LIKE_NEW or ITEM_DAMAGED (since the item was physically received)

return/verification_failed 🔴

  • Description: Triggered when returned item(s) fail verification criteria
  • Common Reasons:
    • Item condition doesn't match approved return case
    • Missing item(s) in the approved return case
    • Wrong item(s) returned
  • Integration Note: May require manual review or customer communication
  • Key Fields to Monitor:
    • verification_status: Will be "FAILED"
    • return_case_items[*].verification_summary.verification_result: one or more of the return case items will be "ITEM_NOT_RECEIVED" or "ITEM_DAMAGED"
    • return_case_items[*].remittance_decision: will be "PENDING" for all return case items if merchant input is required. If all return case items were verified to be "ITEM_LIKE_NEW" or "ITEM_NOT_RECEIVED", the decision will be populated as "REMIT" and "DO_NOT_REMIT" respectively as merchant input is not required.
    • undeclared_items: may or may not be populated with additional verified items included in the physical return that were not declared in the original approved return case. If populated, these items may require manual review or customer communication. Note that the presence of undeclared items does not influence the overall return case verification status.
    • Note on verification_result values:
      • For return_case_items: possible values are ITEM_LIKE_NEW, ITEM_NOT_RECEIVED, or ITEM_DAMAGED
      • For undeclared_items: possible values are only ITEM_LIKE_NEW or ITEM_DAMAGED (since the item was physically received)

Dispute Events

return/dispute_started

  • Description: Triggered when a return case with a failed verification requires action by the merchant.
  • Significance: Remittance decisions will remain in a "PENDING" state until actioned by the merchant.
  • Integration Note: Use this event to trigger notifications to the merchant to take action on failed verifications.
  • Key Fields to Monitor:
    • return_case_items[*].remittance_decision: will be "PENDING"

return/dispute_resolved

  • Description: Triggered when a return case with a failed verification is actioned by the merchant.
  • Significance: Critical trigger for payment processing systems
  • Integration Note: Use this event to trigger customer refunds, exchanges, store credit or gift card issuance
  • Key Fields to Monitor:
    • return_case_items[*].remittance_decision: "REMIT" or "DO_NOT_REMIT" depending on merchant input.

Final Resolution Event

return/remitted

  • Description: Triggered when the return is complete and compensation issued. This event is triggered if ReturnBear is the authorized RMA platform to issue compensation for the return. This may not be the case if the return is processed by a third-party RMA platform.
  • Conditions: Follows successful verification
  • Key Fields to Monitor:
    • status: Will be "REMITTED"
    • return_method: Type of compensation issued
    • fees: Final fee calculations

Best Practices for Webhook Integration

  1. Always verify the event_type before processing
  2. Implement idempotency using the happened_at timestamp
  3. For payment processing, use return/verification_passed as your trigger event
  4. Monitor the tracking_events array for complete return journey visibility
  5. Store the uid and short_uid for easy return reference