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": "demo@returnbear.com",
            "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"
            },
            // one of [RETURN_POINT, COURIER, AWAITING_RETURN_METHOD]
            "method": "RETURN_POINT"
        },
        // 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 support@returnbear.com 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

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