openapi: 3.1.0
info:
  title: Return
  description: >
    ## Overview
    
    For partners who would like to receive notifications of the events triggered for their returns and
    when they are being refunded.
    
    
    ## Manage Webhook Subscription
    
    Partners can subscribe to this webhook by following the steps here: <a href=".."
    target="_blank">Webhook set up</a>.
    
    
    ## Triggers/Events
    
    The `return.asn` webhook type is triggered when one of the following happens in the Happy Returns
    system:
    
    
    - A drop-off method is created for the return.  This occurs when a return is started or when the
    customer changes their desired drop-off method.
    
    - The return status is updated.  This occurs when a return is started, dropped off, approved for 
    a refund, or expired.
    
    
    In order to reduce the volume of requests you will receive, Happy Returns will internally aggregate
    requests for the same return that occur within 60 seconds of each other.  In this
    
    scenario, the otherEvents field will be populated with the events that have been aggregated.  If both
    a drop-off method and return status event
    
    exist in the same payload, the latest return status will always be the primary event. If there are
    multiple events, then they are ordered in reverse chronological order with latest event being first.

webhooks:
  Return Details:
    post:
      requestBody:
        summary: Return details
        description: 'Details about a return. <br />
                      The header contains the `X-Hr-Signature`. For example,
                  
                      ```
                      X-Hr-Signature: bab3130e011ba9522d5919bcf9075649b24f9fdfc928b3d2accc99a53aaf3c34
                      ``` 
                      <br /><br />
                      See here for more information: <a href="/partner/webhooks/#section/Webhook-Validation" target="_blank">Webhook Validation</a>
                      <br /><br />
                      <ul>
                        <li>
                          The payload consists of a return''s items of the same order number. 
                          For example, if a return consists of multiple order numbers, Happy Returns will POST to the webhook URL multiple times for the same return, one request per order number.
                          In the report, each line item is one physical item. NOTE: For some fields, such as the SKU, in order for a value to be populated the information must be passed from the retailer’s ecommerce platform to the Happy Returns system.
                        </li>
                        <li>
                          If the customer decides to do a walk-up return where he/she would go to the retailer store and return, then an event is also triggered. See example on the right.
                        </li>
                        <li>
                          If the there is an extra item in the return bag processed at the hub, then the retailer will be notified for it with some basic information. See example on the right.
                        </li>
                      </ul>
                      '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEvent'
            examples:
              RB Return Started:
                summary: Return Bar - Return Started
                value:
                  event: return_status_updated
                  typeID: started
                  retailerID: modern-retailer
                  otherEvents:
                    - event: return_dropoff_method_created
                      typeID: return-bar
                  items:
                    - happyReturnsReturnID: 5035789d-f873-4bad-b2f3-2daca346c111
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      externalRMAID: RMA20240101A
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-0-5
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: return-bar
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T21:26:39.708039Z'
                      retailerRefundID: ''
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRQJB237
                      happyReturnsItemID: 98fec46c-b16c-4c62-8f09-bc6263006bf8
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
              Mail Return Started:
                summary: Mail - Return Started
                value:
                  event: return_status_updated
                  typeID: started
                  retailerID: modern-retailer
                  otherEvents:
                    - event: return_dropoff_method_created
                      typeID: mail
                  items:
                    - happyReturnsReturnID: 32362eab-1271-4223-980a-cbf220794081
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      externalRMAID: ABC@124
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-3-3
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T22:22:15.07135Z'
                      approvedAt:
                      expiredAt:
                      retailerRefundID: ''
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-8145479669268903
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRPZ2L44
                      happyReturnsItemID: cf3195fd-dbb6-46de-8814-5551a118b96c
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
                    - happyReturnsReturnID: 32362eab-1271-4223-980a-cbf220794081
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-2-3
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T22:22:15.062818Z'
                      approvedAt:
                      expiredAt:
                      retailerRefundID: ''
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-8145479669268903
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentCarrier: ups
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRPZ2L44
                      happyReturnsItemID: 0f4caa2e-0ad5-45b6-bd3d-33f1b50db125
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
              Dropoff Updated:
                summary: Return Dropoff Method updated
                value:
                  event: return_dropoff_method_created
                  typeID: mail
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: 5035789d-f873-4bad-b2f3-2daca346c111
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-0-5
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T21:26:39.708039Z'
                      approvedAt:
                      expiredAt:
                      retailerRefundID: ''
                      returnShipmentLabelUrl: shipment url will go here
                      returnShipmentTracking: HR-UPS-DEV-0971288096304085
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRQJB237
                      happyReturnsItemID: 98fec46c-b16c-4c62-8f09-bc6263006bf8
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
              RB Partial Refund:
                summary: Return Bar - Partial Refund
                value:
                  event: return_status_updated
                  typeID: partial-refund
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: 956a2231-9324-4f8a-a7da-ce275f2c4aa8
                      purchasedAt: '2024-01-08T17:46:55-05:00'
                      email: customer@example.com
                      orderNumber: '273608'
                      orderID: '5330664685634'
                      orderLineItemID: 13389733101634-0-10
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: The UPS Store
                      locationID: TUPSSUS0001
                      locationMetro: San Diego
                      dropoffMethod: return-bar
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-08T23:07:14.649424Z'
                      approvedAt: '2024-01-08T23:09:30.765662Z'
                      expiredAt:
                      retailerRefundID: '897518436418'
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRKTB5PJ
                      happyReturnsItemID: c49c3912-a5d2-42ba-b35b-5b51f1aff9a3
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: return-bar
                      returnBagBarcodes: ["HR3000125650"]
                    - happyReturnsReturnID: 956a2231-9324-4f8a-a7da-ce275f2c4aa8
                      purchasedAt: '2024-01-08T17:46:55-05:00'
                      email: customer@example.com
                      orderNumber: '273608'
                      orderID: '5330664685634'
                      orderLineItemID: 13389733101634-1-10
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: The UPS Store
                      locationID: TUPSSUS0001
                      locationMetro: San Diego
                      dropoffMethod: return-bar
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-08T23:07:14.660248Z'
                      approvedAt:
                      expiredAt:
                      retailerRefundID: ''
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRKTB5PJ
                      happyReturnsItemID: a7e68f20-0ae5-462c-931a-8359baa5ae2b
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
              Mail Partial Refund:
                summary: Mail - Partial Refund
                value:
                  event: return_status_updated
                  typeID: partial-refund
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: 9a82e135-07a4-4e38-a2fb-5b907a71b822
                      purchasedAt: '2024-01-05T17:51:27-05:00'
                      email: customer@example.com
                      orderNumber: '272037'
                      orderID: '5325214515266'
                      orderLineItemID: 13378058223682-3-3
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T23:04:17.196503Z'
                      approvedAt: '2024-01-05T23:34:33.197921Z'
                      expiredAt:
                      retailerRefundID: '897238138946'
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-6775988056215073
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HR2SAP27
                      happyReturnsItemID: 7aa12535-0e52-4236-accc-73ada14f7367
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: happy-returns-hub-inspection
                      returnBagBarcodes: []
                    - happyReturnsReturnID: 9a82e135-07a4-4e38-a2fb-5b907a71b822
                      purchasedAt: '2024-01-05T17:51:27-05:00'
                      email: customer@example.com
                      orderNumber: '272037'
                      orderID: '5325214515266'
                      orderLineItemID: 13378058223682-2-3
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T23:04:17.181408Z'
                      approvedAt:
                      expiredAt:
                      retailerRefundID: ''
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-6775988056215073
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HR2SAP27
                      happyReturnsItemID: 1432be8e-2320-4e9b-9fc0-70372ec10888
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
              RB Return Completed:
                summary: Return Bar - Return Completed
                value:
                  event: return_status_updated
                  typeID: complete
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: 1d22fe61-5ad1-458d-9ed6-b88dad2ac64f
                      purchasedAt: '2024-01-05T17:51:27-05:00'
                      email: customer@example.com
                      orderNumber: '272037'
                      orderID: '5325214515266'
                      orderLineItemID: 13378058223682-4-2
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: The UPS Store
                      locationID: TUPSSUS0001
                      locationMetro: San Diego
                      dropoffMethod: return-bar
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-08T22:28:02.911665Z'
                      approvedAt: '2024-01-08T22:32:56.171645Z'
                      expiredAt:
                      retailerRefundID: '897511784514'
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRZJK6AV
                      happyReturnsItemID: 5903e5c5-c18a-49b7-9718-ad2e3f390f4c
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: return-bar
                      returnBagBarcodes: ["HR3000125650"]
              Mail Return Completed:
                summary: Mail - Return Completed
                value:
                  event: return_status_updated
                  typeID: complete
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: 32362eab-1271-4223-980a-cbf220794081
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-3-3
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T22:22:15.07135Z'
                      approvedAt: '2024-01-05T22:32:45.218294Z'
                      expiredAt:
                      retailerRefundID: '897229783106'
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-0971288096304085
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRPZ2L44
                      happyReturnsItemID: cf3195fd-dbb6-46de-8814-5551a118b96c
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: mail-departure
                      returnBagBarcodes: []
                    - happyReturnsReturnID: 32362eab-1271-4223-980a-cbf220794081
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-2-3
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T22:22:15.062818Z'
                      approvedAt: '2024-01-05T22:32:45.218294Z'
                      expiredAt:
                      retailerRefundID: '897229783106'
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-097128809630408
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: 764
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRPZ2L44
                      happyReturnsItemID: 0f4caa2e-0ad5-45b6-bd3d-33f1b50db125
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: mail-departure
                      returnBagBarcodes: []
              Mail Returnless Refund:
                summary: Mail - Returnless Refund
                value:
                  event: return_status_updated
                  typeID: complete
                  retailerID: modern-retailer
                  otherEvents:
                    - event: return_dropoff_method_created
                      typeID: mail
                    - event: return_status_updated
                      typeID: started
                  items:
                    - happyReturnsReturnID: edb1569b-e11c-4698-b5db-998a52e4f855
                      purchasedAt: '2024-01-05T17:40:17-05:00'
                      email: customer@example.com
                      orderNumber: '272036'
                      orderID: '5325181452354'
                      orderLineItemID: 13377991508034-0-3
                      sku: SKU7890
                      upc: '71234567894'
                      productVariantID: '39941897125954'
                      labelBarcode: '71234567894'
                      productName: "'THE ANGLER' CABANA"
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: mail
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T22:41:04.802446Z'
                      approvedAt: '2024-01-05T22:41:07.932602Z'
                      expiredAt:
                      retailerRefundID: '897230700610'
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRXTYEWC
                      happyReturnsItemID: 18f47043-13fb-4fe7-bb8d-17f81dac88c7
                      value: '128.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '8.0'
                      weightUnit: oz
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: XS
                      approvedMethod: returnless-refund
                      returnBagBarcodes: []
              Walkup Return:
                summary: Walkup Return
                value:
                  event: return_status_updated
                  typeID: complete
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: afebc866-57aa-4f2e-b76e-0c8041f1f95f
                      purchasedAt: '2024-01-05T16:26:05-05:00'
                      email: customer@example.com
                      orderNumber: '272034'
                      orderID: '5324938444866'
                      orderLineItemID: 13377523220546-1-4
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: Modern Retailer Storefront
                      locationID: mrs
                      locationMetro: Los Angeles
                      dropoffMethod: retailer-store
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-05T22:09:21.474892Z'
                      approvedAt: '2024-01-05T22:09:21.148983Z'
                      expiredAt:
                      retailerRefundID: '897226506306'
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: '1ZGH68910307983941'
                      locationShipmentCarrier: 'ups'
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRUGLZTE
                      happyReturnsItemID: 13a180ad-2f10-4812-a59e-08111b8316de
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: retailer-store
                      returnBagBarcodes: ["HR3000125650"]
              Return Expired:
                summary: Return Expired
                value:
                  event: return_status_updated
                  typeID: expired
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: e97c9516-279d-4e44-8f90-7dd37b79684a
                      purchasedAt: '2024-01-08T17:46:55-05:00'
                      email: customer@example.com
                      orderNumber: '273608'
                      orderID: '5330664685634'
                      orderLineItemID: 13389733101634-1-9
                      sku: nomshrts-1
                      upc: SKDFHWEW-DKFD
                      productVariantID: '39942123880514'
                      labelBarcode: SKDFHWEW-DKFD
                      productName: Nomadic Coast Short
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: return-bar
                      country: United States
                      countryCode: US
                      startedAt: '2024-01-11T18:21:42.34585Z'
                      approvedAt:
                      expiredAt: '2024-01-11T18:34:59.378038Z'
                      retailerRefundID: ''
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: ''
                      happyReturnsExpressCode: HRARMEJK
                      happyReturnsItemID: cc3d9bdc-58fa-4167-a19a-4e12d77a3f38
                      value: '50.00'
                      currencyCode: USD
                      hsCode: ''
                      weight: '0.4'
                      weightUnit: lb
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: '29'
                        - label: Color
                          value: Olive
                      approvedMethod: ''
                      returnBagBarcodes: []
              RB Return Dropped off:
                summary: Return Bar - Return Dropped off
                value:
                  event: return_status_updated
                  typeID: dropped-off
                  retailerID: happy-returns-flow
                  otherEvents:
                    - event: return_dropoff_method_created
                      typeID: return-bar
                    - event: return_status_updated
                      typeID: started
                  items:
                    - happyReturnsReturnID: ca4aabe5-8561-42d3-9c63-1d16677d8b28
                      purchasedAt: '2025-01-18T00:34:59Z'
                      email: customer@example.com
                      orderNumber: '738069'
                      orderID: '5969536614466'
                      orderLineItemID: 14972908339266-5-5
                      sku: ''
                      upc: ''
                      productVariantID: '39941668831298'
                      labelBarcode: ''
                      productName: 2 Piece Shorts Set - Crop Short Sleeve Top & Shorts Co-ord
                      returnReason: Did not like
                      returnReasonID: did-not-like
                      returnReasonNote: ''
                      categoryID: ''
                      refundType: refund
                      oneClickExchange: ''
                      location: ''
                      locationID: ''
                      locationMetro: ''
                      dropoffMethod: return-bar
                      country: United States
                      countryCode: US
                      startedAt: '2025-01-18T23:59:49.32631Z'
                      approvedAt: null
                      droppedOffAt: '2025-01-19T00:00:50.635299Z'
                      expiredAt: null
                      retailerRefundID: ''
                      returnShipmentLabelUrl: shipping label URL goes here
                      returnShipmentTracking: HR-UPS-DEV-6775988056215073
                      returnShipmentCarrier: ups
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID: null
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRRDJ4PN
                      happyReturnsItemID: 4ec3cc81-2752-4598-80a4-12f5f9020597
                      returnBagBarcodes: [ ]
                      value: '12.95'
                      currencyCode: USD
                      hsCode: ''
                      weight: '8.0'
                      weightUnit: oz
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Size
                          value: S
                        - label: Color
                          value: Black
                      approvedMethod: ''
              Extra Item Received:
                summary: Extra item received
                value:
                  event: return_status_updated
                  typeID: started
                  retailerID: modern-retailer
                  otherEvents: [ ]
                  items:
                    - happyReturnsReturnID: 9cc28d61-d179-42de-9832-e0254af79271
                      purchasedAt: '0001-01-01T00:00:00Z'
                      email: ''
                      orderNumber: ''
                      orderID: ''
                      orderLineItemID: ''
                      sku: ''
                      upc: ''
                      productVariantID: ''
                      labelBarcode: Unknown
                      productName: 'Extra Item: Received at Hub'
                      returnReason: Too big
                      returnReasonID: too-big
                      returnReasonNote: ''
                      categoryID: shoes
                      refundType: refund
                      oneClickExchange: ''
                      location: Van Nuys Hub
                      locationID: vannuys
                      locationMetro: Los Angeles
                      dropoffMethod: return-bar
                      country: ''
                      countryCode: ''
                      startedAt: '2024-01-11T22:44:43.936203Z'
                      approvedAt: '2024-01-11T22:44:43.944005Z'
                      expiredAt:
                      retailerRefundID: ''
                      returnShipmentLabelUrl: ''
                      returnShipmentTracking: ''
                      returnShipmentCarrier: ''
                      locationShipmentTracking: ''
                      locationShipmentCarrier: ''
                      returnShipmentDestinationAddressID:
                      happyReturnsRetailerID: modern-retailer
                      happyReturnsExpressCode: HRR4BE92
                      happyReturnsItemID: 3233d484-421a-4f95-a573-28f32d217104
                      value: ''
                      currencyCode: ''
                      hsCode: ''
                      weight: '8.0'
                      weightUnit: oz
                      countryOfOrigin: ''
                      exchangeSku: ''
                      exchangeUpc: ''
                      exchangeVariantID: ''
                      exchangeProductName: ''
                      exchangeProductAttributes: [ ]
                      productAttributes:
                        - label: Order/Item ID
                          value: Unknown
                      approvedMethod: return-bar
                      returnBagBarcodes: []
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully

components:
  schemas:
    WebhookEvent:
      title: WebhookRBReturnStarted
      description: Webhook Event for Return Bar - Return Started
      type: object
      properties:
        event:
          type: string
          description: The event that triggered the webhook. This can be either `return_dropoff_method_created` or `return_status_updated`.
        typeID:
          type: string
          description: 'The details on the event that triggered the webhook.<br />
                        <ul>
                          <li>If the event is `return_dropoff_method_created`, then the value is the drop-off method. The possible values are: `mail`, `mail-nolabel`, `mail-nobox-nolabel`, `mail-shopper-provided`, `return-bar`, `retailer-store`.</li>
                          <li>If the event is `return_status_updated`, then the value is the new return status. The possible values are `started`, `dropped-off`, `partial-refund`, `expired` and `complete`.</li>
                        </ul>'
        retailerID:
          type: string
          description: The unique identifier for the retailer in the Happy Returns system.
        otherEvents:
          type: array
          items:
            type: object
            properties:
              event:
                type: string
                description: The aggregated event that would have triggered the webhook. This can be either `return_dropoff_method_created` or `return_status_updated`.
              typeID:
                type: string
                description: 'The details on the aggregated event that would have triggered the webhook.
                              <ul>
                                <li>If the `event` is `return_dropoff_method_created`, then the value is the drop-off method. The possible values are: `mail`, `mail-nolabel`, `mail-nobox-nolabel`, `mail-shopper-provided`, `return-bar`, `retailer-store`.</li>
                                <li>If the `event` is `return_status_updated`, then the value is the new return status. The possible values are `started`, `dropped-off`, `partial-refund`, `expired` and `complete`.</li>
                              </ul>'
        items:
          type: array
          items:
            type: object
            properties:
              happyReturnsReturnID:
                type: string
                description: The unique identifier for the return transaction.
              purchasedAt:
                format: date-time
                type: string
                description: The ISO 8601 timestamp in UTC when the order is created.
              email:
                type: string
                description: The customer email.
              orderNumber:
                type: string
                description: A unique identifier for the order as provided by the retailer.
              externalRMAID:
                type: string
                description: The unique identifier for the return generated by the retailer's or partner's internal systems.
              orderID:
                type: string
                description: A unique identifier for the order as provided by the retailer.
              orderLineItemID:
                type: string
                description: 'A unique identifier for each SKU in the order. If an order contains
                              two items of the same SKU, they commonly share the same order line item ID.  If the retailer''s
                              ecommerce platform allows multiple items to be represented by the same line item id, we will suffix
                              the line item id with the offset of the current item and then the total refundable quantity.  As an
                              example, if the ecommerce platform had a line item id of ''12345'' and a quantity of two, there would be
                              up to two items in the return, with orderLineItemID''s of 12345-0-2 and 12345-1-2.'
              sku:
                type: string
                description: A stock keeping unit (SKU) is a unique identifier for a purchasable item in the product catalog.
              upc:
                type: string
                description: A universal product code (UPC) is a unique identifier for a purchasable item in the product catalog.
              productVariantID:
                type: string
                description: A product variant ID is a unique identifier for a purchasable item in the product catalog.
              labelBarcode:
                type: string
                description: The string that is printed as a barcode symbol on the item label. It is commonly the UPC, SKU, or serial number.
              productName:
                type: string
                description: Text that describes the product.
              returnReason:
                type: string
                description: The reason the customer returned the item.
              returnReasonID:
                type: string
                description: The Happy Returns ID of the reason the customer returned the item.
              returnReasonNote:
                type: string
                description: Additional notes about why customer returned item.
              categoryID:
                type: string
                description: 'For retailers who use the return reason by product category feature, the
                              category ID is the identifier used by the retailer to identify the product category.'
              refundType:
                type: string
                description: The refund type is what the customer is getting for the returned item - a Refund, Site credit, or an Exchange.
              oneClickExchange:
                type: string
                description: This field is marked `"true"` when the customer has chosen a one-click exchange; otherwise it is empty.
              location:
                type: string
                description: The name of the location that hosts the Return Bar where the item was dropped off.
              locationID:
                type: string
                description: The Happy Returns ID of the location that hosts the Return Bar where the item was dropped off.
              locationMetro:
                type: string
                description: The name of the metropolitan area where the Return Bar is located.
              dropoffMethod:
                type: string
                description: Contains the current dropoff method for the return.
              country:
                type: string
                description: The country that appears in the shipping address associated to the order.
              countryCode:
                type: string
                description: The two letter ISO country code that appears in the shipping address associated to the order.
              startedAt:
                type: string
                description: The ISO 8601 timestamp in UTC when the customer starts the return of the item(s).
              approvedAt:
                type: string
                description: 'The ISO 8601 timestamp in UTC when the return of the item is confirmed,
                              and the customer is due their refund or exchange.  This field can be used to determine the status of
                              individual items. This field will be blank for items that are not yet approved and will be populated
                              for items that are approved.'
              droppedOffAt:
                type: string
                description: 'The ISO 8601 timestamp in UTC when the item is dropped off.
                              This field will be blank for items that are not yet dropped off and will be populated for items that are dropped off.'
              expiredAt:
                type: string
                description: 'The ISO 8601 timestamp in UTC when the return of the item is expired, and
                              the customer can no longer return the item. This field will be blank for items that are not yet
                              expired and will be populated for items that are expired.'
              retailerRefundID:
                type: string
                description: The ecommerce platform refund ID of the item.
              returnShipmentLabelUrl:
                type: string
                description: The label URL for the shipment. This is populated when the return method is "By mail"; otherwise it is empty.
              returnShipmentTracking:
                type: string
                description: The shipment tracking number. This is populated when the return method is "By mail"; otherwise it is empty.
              returnShipmentCarrier:
                type: string
                description: Transportation carrier name. This is populated when the return method is "By Mail".
              locationShipmentTracking:
                type: string
                description: The Shipment box scanned by the associate during the return. This will be used by merchants receiving shipments via in-store dropoff; otherwise it is empty.
              locationShipmentCarrier:
                type: string
                description: Transportation carrier name. This will be used by merchants receiving shipments via in-store dropoff.
              returnShipmentDestinationAddressID:
                type: integer
                description: The unique identifier for the destination of the return in the Happy Returns system. This is populated when the return method is "By Mail".
              happyReturnsRetailerID:
                type: string
                description: The unique identifier for the retailer in the Happy Returns system.
              happyReturnsExpressCode:
                type: string
                description: The human-friendly identifier for the return transaction also referred to as the `happyReturnsRMAID` and `confirmationCode`.
              happyReturnsItemID:
                type: string
                description: The unique identifier for the returned item.
              value:
                type: string
                description: Item’s value when provided by the retailer to facilitate cross border shipments.  This is the base value and does not adjust for fees, discounts, taxes, etc.
              currencyCode:
                type: string
                description: The 3 digit currency code that is represented by the value field.
              hsCode:
                type: string
                description: Harmonized System (HS) codes when provided by the retailer to facilitate cross border shipments.
              weight:
                type: string
                description: Item’s weight value when provided by the retailer to facilitate cross border shipments.
              weightUnit:
                type: string
                description: Item’s weight unit of measure when provided by the retailer to facilitate cross border shipments.
              countryOfOrigin:
                type: string
                description: Item’s country of origin (2 digit country code) when provided by the retailer to facilitate cross border shipments.
              exchangeSku:
                type: string
                description: The SKU of the new exchange item that replaces the returned item.  This is only populated when the `refundType` is "exchange".
              exchangeUpc:
                type: string
                description: The UPC of the new exchange item that replaces the returned item. This is only populated when the `refundType` is "exchange".
              exchangeVariantID:
                type: string
                description: The product variant ID of the new exchange item that replaces the returned item.  This is only populated when the `refundType` is "exchange".
              exchangeProductName:
                type: string
                description: The name of the product of the new exchange item that replaces the returned item.  This is only populated when the `refundType` is "exchange".
              exchangeProductAttributes:
                type: array
                items:
                  type: object
                  description: An array of product attributes that differentiate an item received in an exchange from other, related products. This is only populated when the refundType is "exchange".
                  properties:
                    label:
                      type: string
                      description: 'The category that this attribute is a part of. Example of values: "Size", "Color", "Material", etc...'
                    value:
                      type: string
                      description: 'The value of the attribute that differentiates this product from other, similiar ones. Example of values: "Large", "Green", "Silk", etc...'
              productAttributes:
                type: array
                description: Represent attributes in the ecommerce platform that differentiate a particular product from other, related products.
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: 'The category that this attribute is a part of. Example of values: "Size", "Color", "Material", etc...'
                    value:
                      type: string
                      description: 'The value of the attribute that differentiates this product from other, similiar ones. Example of values: "Large", "Green", "Silk", etc...'
              approvedMethod:
                type: string
                description: Contains how the item is being approved.
              returnBagBarcodes:
                type: array
                description: The Return Bag Barcode associated with the item. This is visible on the polybag and is populated during drop off. For merchants that use “single scan”, all bags associated to the return will be re-labeled to use a single ID once received at a Happy Returns hub.
                items:
                  type: string