openapi: 3.1.0
info:
  title: Return Webhook
  version: 1.0.0
  description: |
    This notification is sent when the **Return** topic is requested.
    For those that subscribe to this topic for more than one trigger event,
    the `trigger` property is included in the payload for reference.

    | Response Header  | Description               |
    | ---------------- | ------------------------- |
    | X-Loop-Signature | Hashed Webhook Secret Key |

    The X-Loop-Signature is a base64, HMAC hash of body payload using the Webhook Secret provided by Loop.

    Note: Before attempting to create your hash of the POST request body, make sure slashes have been escaped &
    newlines have been removed from the JSON.
webhooks:
  Return:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Return"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully
components:
  schemas:
    Return:
      properties:
        topic:
          type: string
          description: The webhook type.
          examples:
            - return
        trigger:
          type: string
          description: The event that triggered the webhook.
          examples:
            - return.created
            - return.updated
            - return.closed
        shop_id:
          type: integer
          description: The ID of the shop the return belongs to.
          examples:
            - 12345
        id:
          type: string
          description: The Loop return ID.
          examples:
            - "1673"
        state:
          type: string
          description: >
            The state of the return.


            Possible values:

            - `open`: Requests have yet to be processed (Loop has not fully processed all the outcomes).

            - `cancelled`: Refers to any return requests that have been cancelled in the Loop admin.

            - `closed`: Typically refers to any return request/outcome that has been processed or closed manually.
              No further action is required for these returns.

            - `review`: Refers to a return that has been flagged for review.

            - `expired`: The return did not complete before the shop return window ended.
              A `return.updated` webhook fires for this state change.
          enum:
            - open
            - cancelled
            - closed
            - review
            - expired
          examples:
            - open
            - cancelled
            - closed
            - review
            - expired
        refund_before_inspection:
          type: boolean
          description: Whether the return is configured to refund before the items are inspected.
          examples:
            - false
        created_at:
          type: string
          description: The date and time (ISO 8601 format) when the return was created in Loop.
          examples:
            - "2019-04-01T12:00:00+00:00"
        edited_at:
          type:
            - string
            - "null"
          description: >
            Date and time (ISO 8601 format) when the return was last edited inside Loop.
            `null` when the return has not been edited.
          examples:
            - "2019-04-01T12:00:00+00:00"
            - null
        total:
          type: string
          description: The total cost of the return.
          examples:
            - "48.81"
        order_id:
          type: string
          description: The Loop order ID.
          examples:
            - "2871"
        order_name:
          type: string
          description: The order name from the commerce provider (e.g. Shopify).
          examples:
            - "#47727779"
        taxes_included:
          type: boolean
          description: Whether taxes are included in the order's prices. Defaults to false.
          examples:
            - false
        provider_order_id:
          type: string
          description: The order ID from the commerce provider (e.g. Shopify).
          examples:
            - "58997314"
        order_number:
          type: string
          description: The order number from the commerce provider (e.g. Shopify).
          examples:
            - "7078"
        provider_order_number:
          type:
            - integer
            - string
          description: The order number from the commerce provider (e.g. Shopify).
          examples:
            - 8078
        provider_order_external_id:
          type:
            - string
            - "null"
          description: >
            The external order ID from the commerce provider (e.g. Shopify).
            `null` when the order has no external identifier.
          examples:
            - "12354567890"
            - null
        provider_order_sales_channel:
          type:
            - string
            - "null"
          description: The name of the sales channel that the order was created in.
          examples:
            - "Example Online Store"
            - null
        customer:
          type: string
          description: The email address of the customer.
          examples:
            - me@myself.com
        customer_detail:
          type: object
          description: The customer's email, first name, and last name.
          properties:
            email:
              type: string
              description: The customer's email address.
              examples:
                - jf@example.com
            first_name:
              type: string
              description: The customer's first name.
              examples:
                - Jean
            last_name:
              type: string
              description: The customer's last name.
              examples:
                - Launier
        address:
          type: object
          description:
            The original customer's shipping address or the address that the customer inputs
            in the case of a gift return.
          properties:
            name:
              type:
                - string
                - "null"
              maxLength: 100
              description: "The name associated with the address."
              examples:
                - J.F. Launier
            company:
              type:
                - string
                - "null"
              maxLength: 100
              description: "The name of the company residing at the address."
              examples:
                - "Universal Exports"
            address1:
              type: string
              maxLength: 125
              description: "Line 1 of the address."
              examples:
                - 1234 Example Street
            address2:
              type:
                - string
                - "null"
              maxLength: 125
              description: "Line 2 of the address."
              examples:
                - Unit 19
            city:
              type: string
              maxLength: 100
              description: "The city in which the address is located."
              examples:
                - Townsville
            state:
              type: string
              maxLength: 100
              description: "The state or region in which the address is located."
              examples:
                - Louisiana
            zip:
              type:
                - string
                - "null"
              maxLength: 16
              description: "The ZIP or postal code associated with the address."
              examples:
                - "90210"
            country:
              type: string
              description: "The country in which the address is located."
              examples:
                - United States
            country_code:
              type: string
              maxLength: 2
              description: "The country code associated with the address."
              examples:
                - US
            phone:
              type: string
              description: "The phone number associated with the address."
              examples:
                - +1-678-999-8212
        currency:
          type: string
          description: The currency of the store at the time of the order.
          examples:
            - USD
        return_product_total:
          type: string
          description: The value of returned line items, excluding order discounts and taxes.
          examples:
            - "50.00"
        return_discount_total:
          type: string
          description: The sum of all discounts on returned items.
          examples:
            - "5.00"
        return_tax_total:
          type: string
          description: The value of order taxes on returned line items.
          examples:
            - "2.50"
        return_total:
          type: string
          description: The return total after taxes and discounts.
          examples:
            - "47.50"
        return_credit_total:
          type: string
          description: The value of total return credit (product + honored discount + tax).
          examples:
            - "47.50"
        status_page_url:
          type: string
          description: The link to the return status page.
          examples:
            - https://example.loopreturns.com/#/return/b3e4764e-7adf-4b8c-802a-553305b6db49
        exchange_product_total:
          type: string
          description: The value of exchange items before discounts and taxes.
          examples:
            - "60.00"
        exchange_discount_total:
          type: string
          description: The discount on exchange items.
          examples:
            - "10.00"
        exchange_tax_total:
          type: string
          description: The tax on exchange items.
          examples:
            - "3.00"
        exchange_total:
          type: string
          description: The exchange total after taxes and discounts.
          examples:
            - "53.00"
        exchange_credit_total:
          type: string
          description: The total exchange items value after discounts and taxes, which is used by the customer.
          examples:
            - "53.00"
        gift_card:
          type: string
          description: The amount of store credit to be issued to the customer on a gift card.
          examples:
            - "25.00"
        handling_fee:
          type: string
          description: The handling fee amount set in Loop admin.
          examples:
            - "5.00"
        refund:
          type: string
          description: The total refund value of the return.
          examples:
            - "20.00"
        upsell:
          type: string
          description: >
            The additional amount paid by customer when exchange credit total is greater than return credit total.
          examples:
            - "10.00"
        is_gift_return:
          type: boolean
          description: Whether or not the return is a gift return.
          examples:
            - true
            - false
        refunds:
          type: array
          description: The breakdown of refunds across payment gateways.
          items:
            type: object
            properties:
              gateway:
                type: string
                description: The payment gateway in which a refund was processed.
                examples:
                  - Stripe
              amount:
                type: string
                description: The refund amount issued to a gateway.
                examples:
                  - "20.00"
              currency:
                type: string
                description: The currency used in the refund.
                examples:
                  - USD
              provider_refund_id:
                type: [string, "null"]
                examples:
                  - "987654321"
                  - "refr_01j82vdkny7jn4yn69hwgtc84b"
                description: >
                  The unique identifier associated with the refund,
                  assigned by the commerce provider (e.g. Shopify).
              provider:
                type: string
                examples:
                  - "stripe"
                  - "reshop"
                  - "shopify_payments"
                  - "loop"
                description: The provider who the handled the refund.
        labels:
          type: array
          description: Details on each label associated with the return.
          items:
            type: object
            properties:
              status:
                type: string
                description: The status of the return shipping label.
                examples:
                  - new
              updated_at:
                type: string
                description: The date and time at which the label was last updated, in `Y-m-d H:i:s` format.
                examples:
                  - 2024-02-02 21:19:04
              url:
                type: string
                description: The link to the label details.
                examples:
                  - https://partner.loopreturns.com/label/12345456
              rate:
                type:
                  - integer
                  - "null"
                description: The shipping rate paid for the label.
                examples:
                  - 1093
              carrier:
                type: string
                description: The carrier associated with the label.
                examples:
                  - USPS
              tracking_number:
                type:
                  - string
                  - "null"
                description: The tracking number associated with the label.
                examples:
                  - "123456789101112"
              line_items:
                type: array
                description: A list of line item IDs associated with the label.
                items:
                  type: integer
                  examples:
                    - 987654321
                    - 123456789
        line_items:
          type: array
          description: Details on items being sent to Loop as part of the return.
          items:
            type: object
            properties:
              line_item_id:
                type: string
                description: The Loop line item ID.
                examples:
                  - "123456789"
              provider_line_item_id:
                type: string
                description: The order line item ID from the commerce provider (e.g. Shopify).
                examples:
                  - "12149029339269"
              product_id:
                type: string
                description: The product ID from the commerce provider (e.g. Shopify).
                examples:
                  - "5107813056645"
              variant_id:
                type: string
                description: The variant ID from the commerce provider (e.g. Shopify).
                examples:
                  - "34404555554949"
              sku:
                type: string
                description: >
                  The variant SKU from the commerce provider (e.g. Shopify).
                  Empty string when the line item has no SKU.
                examples:
                  - "new-sku"
                  - ""
              barcode:
                type: string
                description: >
                  The barcode from the commerce provider (e.g. Shopify).
                  Empty string when the line item has no barcode.
                examples:
                  - "barcode1234"
                  - ""
              title:
                type: string
                description: The product title from the commerce provider (e.g. Shopify).
                examples:
                  - "Retro Laser - Big"
              weight_in_grams:
                type:
                  - integer
                  - "null"
                description: The weight of the line item in grams.
                examples:
                  - 226
                  - null
              price:
                type: string
                description: The price paid by customer before discounts and tax.
                examples:
                  - "35.38"
              discount:
                type: string
                description: The discount on the item.
                examples:
                  - "0.00"
              tax:
                type: string
                description: The tax on the item.
                examples:
                  - "2.65"
              refund:
                type: string
                description: The amount refunded to customer for this item.
                examples:
                  - "38.03"
              returned_at:
                type: string
                description: The date and time (ISO 8601 format) when the return was created in Loop.
                examples:
                  - "2024-01-11T22:47:02+00:00"
              exchange_variant:
                type: string
                description: >
                  The variant ID (from the commerce provider, e.g. Shopify) for the replacement product
                  when the item is an exchange.
                  Empty string when there is no exchange variant.
                examples:
                  - "23141001"
                  - ""
              return_reason:
                type: string
                description: The reason for return as selected by the customer in Loop.
                examples:
                  - "I didn't like how the item looked"
              provider_restock_location_id:
                type:
                  - integer
                  - "null"
                description: The location ID from the commerce provider (e.g. Shopify) for line item restocking.
                examples:
                  - 6543
                  - null
              is_in_store_return:
                type: boolean
                description:
                  True if the return is made in-store through the Loop Point of Sale application;
                  false if made online through the returns portal.
                examples:
                  - false
              provider_location_id:
                type:
                  - integer
                  - "null"
                description: >
                  The location ID from the commerce provider (e.g. Shopify) for the line item
                  (fulfillment / origin context).
                  Not the return shipping destination; see `destination_provider_location_id` for that.
                examples:
                  - 1456
                  - null
              parent_return_reason:
                type:
                  - string
                  - "null"
                description: The parent reason for return as selected by the customer in Loop.
                examples:
                  - "I didn't like the item"
                  - null
              return_comment:
                type: string
                description: The return reason comment.
                examples:
                  - "N/A"
              outcome:
                type: string
                description: >
                  The line item outcome, representing the action determined for this item.
                  When multiple outcomes apply (e.g. a workflow adds "keep" alongside
                  the initial "default"), this field reflects the most specific outcome.


                  Possible values:

                  - `default`: Standard return — the item is expected to be shipped back.

                  - `keep`: The customer keeps the item (Keep Item policy or workflow).

                  - `donate`: The customer donates the item.

                  - `review`: The item has been flagged for manual review.

                  - `reject`: The item has been rejected (not eligible for return).
                examples:
                  - "default"
                  - "keep"
                  - "donate"
                  - "review"
                  - "reject"
              taxes:
                type: array
                description: The tax information for the line item.
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      description: The name of the tax.
                      examples:
                        - "State Tax"
                    amount:
                      type: integer
                      description: The tax amount in minor units (cents).
                      examples:
                        - 265
                    rate:
                      type:
                        - number
                        - "null"
                      description: The tax rate.
                      examples:
                        - 0.0625
              fulfillment_sku:
                type: string
                description: >
                  The fulfillment SKU mapped from the customer SKU. Only present when the shop has the
                  "Include fulfillment SKU in return data" setting enabled.
                examples:
                  - "FULFIL-SKU-123"
        exchanges:
          type: array
          description: Details about the product(s) being sent to the customer.
            This can be a result of an even exchange, replacements for returned items,
            or new purchases made through the app.
          items:
            type: object
            properties:
              exchange_id:
                type: string
                description: The Loop exchange ID.
                examples:
                  - "1417"
              product_id:
                type: string
                description: The product ID from the commerce provider (e.g. Shopify).
                examples:
                  - "69713389"
              variant_id:
                type: string
                description: The variant ID from the commerce provider (e.g. Shopify).
                examples:
                  - "9502968"
              exchange_order_name:
                type: string
                description: The new exchange order name from the commerce provider (e.g. Shopify).
                examples:
                  - "#EXC-5551-1"
              exchange_order_id:
                type: string
                description: The new exchange order ID from the commerce provider (e.g. Shopify).
                examples:
                  - "459765194"
              sku:
                type: string
                description: >
                  The variant SKU from the commerce provider (e.g. Shopify).
                  Empty string when the exchange item has no SKU.
                examples:
                  - "example-sku-123"
                  - ""
              type:
                type: string
                description: The exchange type.
                examples:
                  - "exchange"
              title:
                type: string
                description: The product title from the commerce provider (e.g. Shopify).
                examples:
                  - "T-Shirt - Large"
              price:
                type: string
                description: The price of exchange item before discounts and tax.
                examples:
                  - "99.11"
              discount:
                type: string
                description: The discount on the exchange item.
                examples:
                  - "0.00"
              tax:
                type: string
                description: The tax on the exchange item.
                examples:
                  - "0.00"
              total:
                type: string
                description: The price of exchange item after discounts and tax.
                examples:
                  - "99.11"
              out_of_stock:
                type: boolean
                description: Whether the item is out of stock.
                examples:
                  - true
              out_of_stock_resolution:
                type:
                  - string
                  - "null"
                description: The resolution if the item is out of stock; `null` if not applicable.
                examples:
                  - "credited"
                  - "refunded"
                  - null
        shipment_id:
          type: string
          description: The Happy Returns shipment ID.
          examples:
            - "SHIP-001"
        carrier:
          type: string
          description: The name of the carrier or N/A if the carrier has not yet been assigned.
          examples:
            - "USPS"
            - "N/A"
        tracking_number:
          type: string
          description: The tracking number provided by the carrier or N/A if the carrier has not yet been assigned.
          examples:
            - "28735625627856237856287"
            - "N/A"
        label_status:
          type: string
          description: >
            Status of the shipment according to EasyPost:

            - no shipment status

            - pre_transit

            - in_transit

            - out_for_delivery

            - delivered

            - error

            - failure


            N/A if no label status has been provided yet.
          examples:
            - pre_transit
            - delivered
        label_updated_at:
          type: string
          description: |
            The date and time (ISO 8601 format) when the last status update occurred.


            N/A: label not yet updated.
          examples:
            - "2025-11-07T01:47:42+00:00"
            - "N/A"
        destination_id:
          type:
            - integer
            - "null"
          description: The Loop destination ID. `null` when the return has no destination.
          examples:
            - 2232
            - null
        destination_provider_location_id:
          type:
            - integer
            - "null"
          description: |
            The commerce platform's numeric location ID for the **return shipping destination**
            (the same destination as `destination_id`), when that destination has a linked Loop location.
            `null` when no location is linked or when the return has no destination. This is separate from
            `line_items[].provider_location_id`, which describes fulfillment/origin context per line item.
          examples:
            - 987654321
            - null
        return_method:
          type:
            - object
            - "null"
          description:
            If the return is not being sent back through boxing and shipping,
            this field describes the way in which the item is being returned.
            These are usually pick-up or drop-off options.
          properties:
            provider:
              type: string
              description: The provider of the return method.
              examples:
                - "happy-returns"
            return_method_type:
              type: string
              description: The return method type.
              examples:
                - "drop-off"
                - "pick-up"
            scannable_id:
              type:
                - string
                - "null"
              description: The identifier that can be scanned at the warehouse to connect to the return data.
              examples:
                - "23124100124923"
            address:
              type: object
              description: If the return method is a drop-off, this is the destination where it can be dropped off at.
              properties:
                name:
                  type: [string, "null"]
                  description: The name associated with the address.
                company:
                  type: [string, "null"]
                  description: The name of the company residing at the address.
                address1:
                  type: string
                  description: Line 1 of the address.
                address2:
                  type: [string, "null"]
                  description: Line 2 of the address.
                city:
                  type: string
                  description: The city in which the address is located.
                state:
                  type: [string, "null"]
                  description: The state or region in which the address is located.
                zip:
                  type: string
                  description: The ZIP or postal code associated with the address.
                country:
                  type: string
                  description: The country in which the address is located.
                country_code:
                  type: [string, "null"]
                  description: The country code associated with the address.
                phone:
                  type: [string, "null"]
                  description: The phone number associated with the address.
                latitude:
                  type: [number, "null"]
                  description: The latitude of the drop-off location.
                longitude:
                  type: [number, "null"]
                  description: The longitude of the drop-off location.
              example:
                name: "Staples 0152"
                company: null
                address1: "7881 Edinger Ave.Ste.130"
                address2: "Bella Terra Mall"
                city: "Huntington Beach"
                state: "CA"
                zip: "92647"
                country: "United States of America"
                country_code: "US"
                phone: ""
                latitude: 33.7313927
                longitude: -117.9910687
            state:
              type: string
              description: The state of the return method at the current time, similar to label status.
              examples:
                - "new"
                - "in_transit"
            rma_id:
              type: string
              description: The ID of the return record in the related system.
              examples:
                - "HRABC123"
            qr_code_url:
              type: string
              description: If the return method has a QR code, this is the link; otherwise null.
              examples:
                - "https://partner.happyreturns.com/barcode/qr?code=HRABC123"
                - null
            updated_at:
              type:
                - string
                - "null"
              description: The date and time at which the return method was last updated.
              examples:
                - "2024-02-02 21:19:04"
                - null
            scheduled_at:
              type:
                - string
                - "null"
              description: If this return method needs to be scheduled for pick up or drop off; otherwise null.
              examples:
                - null
                - "2019-04-01T12:00:00+00:00"
        package_reference:
          type:
            - string
            - "null"
          description: >
            The value that identifies the physical package that the return is in
            regardless if it was returned via box & ship
            or a different return method.
          examples:
            - "PKG-12345"
        type:
          type: string
          description: The return type.
          examples:
            - standard
            - warranty
