LiquiDonate · AsyncAPI Specification

ReturnsDirect by LiquiDonate - Return and Refund Events

Version 1.0.0-beta

Outbound webhook event surface for ReturnsDirect by LiquiDonate. LiquiDonate POSTs return and refund status events to the webhook URL a retailer registers, so the retailer can update its own order management system. Every event is signed with HMAC-SHA256 over the raw request body using the shared secret LiquiDonate provisions for the shop, sent as lowercase hex in `X-Signature` alongside `X-Shop-Domain`. Verify with a timing-safe comparison before trusting the payload. This AsyncAPI was generated by the API Evangelist enrichment pipeline from the published webhook catalog and payload examples at https://docs-returns.liquidonate.com. LiquiDonate does not publish an AsyncAPI definition; every event name, field and example here is taken verbatim from that documentation.

View Spec View on GitHub Reverse LogisticsReturns ManagementDonationsNonprofitsRetailEcommerceSustainabilityCircular EconomyShippingSupply ChainExcess InventoryCompanyAsyncAPIWebhooksEvents

Channels

returnsDirectEvents
The retailer-registered webhook endpoint LiquiDonate POSTs all return and refund status events to.

Messages

✉
return_pending
return.pending
A return request was created and is awaiting processing.
✉
return_pending_approval
return.pending_approval
A return is waiting on retailer or LiquiDonate approval.
✉
return_approved
return.approved
A return was approved.
✉
return_rejected
return.rejected
A return was rejected.
✉
return_cancelled
return.cancelled
A return was cancelled.
✉
refund_completed
refund.completed
A refund for an approved return completed.
✉
refund_flagged
refund.flagged
A refund was flagged for review rather than completing.

Servers

https
retailerWebhook
The retailer-operated HTTPS endpoint registered with LiquiDonate to receive events.

AsyncAPI Specification

Raw ↑ 
asyncapi: 3.0.0
info:
  title: ReturnsDirect by LiquiDonate - Return and Refund Events
  version: 1.0.0-beta
  description: 'Outbound webhook event surface for ReturnsDirect by LiquiDonate. LiquiDonate POSTs return
    and refund status events to the webhook URL a retailer registers, so the retailer can update its own
    order management system.


    Every event is signed with HMAC-SHA256 over the raw request body using the shared secret LiquiDonate
    provisions for the shop, sent as lowercase hex in `X-Signature` alongside `X-Shop-Domain`. Verify
    with a timing-safe comparison before trusting the payload.


    This AsyncAPI was generated by the API Evangelist enrichment pipeline from the published webhook catalog
    and payload examples at https://docs-returns.liquidonate.com. LiquiDonate does not publish an AsyncAPI
    definition; every event name, field and example here is taken verbatim from that documentation.'
  contact:
    name: LiquiDonate
    url: https://docs-returns.liquidonate.com
    email: sales@liquidonate.com
defaultContentType: application/json
servers:
  retailerWebhook:
    host: your-system.com
    protocol: https
    description: The retailer-operated HTTPS endpoint registered with LiquiDonate to receive events.
    security:
    - $ref: '#/components/securitySchemes/hmacSignature'
channels:
  returnsDirectEvents:
    address: /webhooks/returnsdirect-rms
    title: ReturnsDirect return and refund events
    description: The retailer-registered webhook endpoint LiquiDonate POSTs all return and refund status
      events to.
    servers:
    - $ref: '#/servers/retailerWebhook'
    messages:
      return_pending:
        $ref: '#/components/messages/return_pending'
      return_pending_approval:
        $ref: '#/components/messages/return_pending_approval'
      return_approved:
        $ref: '#/components/messages/return_approved'
      return_rejected:
        $ref: '#/components/messages/return_rejected'
      return_cancelled:
        $ref: '#/components/messages/return_cancelled'
      refund_completed:
        $ref: '#/components/messages/refund_completed'
      refund_flagged:
        $ref: '#/components/messages/refund_flagged'
operations:
  receiveReturnsDirectEvent:
    action: receive
    channel:
      $ref: '#/channels/returnsDirectEvents'
    title: Receive a return or refund status event
    summary: LiquiDonate sends return and refund lifecycle events to the retailer webhook URL.
    messages:
    - $ref: '#/channels/returnsDirectEvents/messages/return_pending'
    - $ref: '#/channels/returnsDirectEvents/messages/return_pending_approval'
    - $ref: '#/channels/returnsDirectEvents/messages/return_approved'
    - $ref: '#/channels/returnsDirectEvents/messages/return_rejected'
    - $ref: '#/channels/returnsDirectEvents/messages/return_cancelled'
    - $ref: '#/channels/returnsDirectEvents/messages/refund_completed'
    - $ref: '#/channels/returnsDirectEvents/messages/refund_flagged'
components:
  securitySchemes:
    hmacSignature:
      type: httpApiKey
      in: header
      name: X-Signature
      description: HMAC-SHA256 of the raw request body using the shop shared secret, lowercase hex.
  messages:
    return_pending:
      name: return.pending
      title: return.pending
      summary: A return request was created and is awaiting processing.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: return.pending
        payload:
          event: return.pending
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: pending
          refundStatus: pending
          refundAmount: null
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
    return_pending_approval:
      name: return.pending_approval
      title: return.pending_approval
      summary: A return is waiting on retailer or LiquiDonate approval.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: return.pending_approval
        payload:
          event: return.pending_approval
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: pending_approval
          refundStatus: pending
          refundAmount: null
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
    return_approved:
      name: return.approved
      title: return.approved
      summary: A return was approved.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: return.approved
        payload:
          event: return.approved
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: approved
          refundStatus: pending
          refundAmount: null
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
    return_rejected:
      name: return.rejected
      title: return.rejected
      summary: A return was rejected.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: return.rejected
        payload:
          event: return.rejected
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: rejected
          refundStatus: pending
          refundAmount: null
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
    return_cancelled:
      name: return.cancelled
      title: return.cancelled
      summary: A return was cancelled.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: return.cancelled
        payload:
          event: return.cancelled
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: cancelled
          refundStatus: pending
          refundAmount: null
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
    refund_completed:
      name: refund.completed
      title: refund.completed
      summary: A refund for an approved return completed.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: refund.completed
        payload:
          event: refund.completed
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: approved
          refundStatus: completed
          refundAmount: 89.98
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
    refund_flagged:
      name: refund.flagged
      title: refund.flagged
      summary: A refund was flagged for review rather than completing.
      contentType: application/json
      headers:
        type: object
        properties:
          X-Shop-Domain:
            type: string
            description: Your shop identifier.
          X-Signature:
            type: string
            description: HMAC-SHA256 of the raw body, lowercase hex.
          Content-Type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ReturnEvent'
      examples:
      - name: refund.flagged
        payload:
          event: refund.flagged
          shop: acme.com
          parcelId: 101
          rmaId: '1001'
          externalOrderId: order_99001
          orderNumber: '#1001'
          status: approved
          refundStatus: flagged
          refundAmount: 89.98
          refundMethod: cash
          updatedAt: '2026-03-07T09:05:00.000Z'
  schemas:
    ReturnEvent:
      type: object
      description: Return or refund status event payload.
      properties:
        event:
          type: string
          enum:
          - return.pending
          - return.pending_approval
          - return.approved
          - return.rejected
          - return.cancelled
          - refund.completed
          - refund.flagged
          description: Event name.
        shop:
          type: string
          description: Your shop identifier.
          examples:
          - acme.com
        parcelId:
          type: integer
          description: LiquiDonate parcel identifier.
          examples:
          - 101
        rmaId:
          type: string
          description: Return Merchandise Authorization identifier.
          examples:
          - '1001'
        externalOrderId:
          type: string
          description: Your order identifier, as pushed on the order.
          examples:
          - order_99001
        orderNumber:
          type: string
          examples:
          - '#1001'
        status:
          type: string
          enum:
          - pending
          - pending_approval
          - approved
          - rejected
          - cancelled
          description: Current return status.
        refundStatus:
          type: string
          enum:
          - pending
          - completed
          - flagged
          description: Current refund status.
        refundAmount:
          type:
          - number
          - 'null'
          description: Refund amount once known, otherwise null.
        refundMethod:
          type: string
          examples:
          - cash
        updatedAt:
          type: string
          format: date-time
      required:
      - event
      - shop
      - parcelId
      - rmaId
      - externalOrderId
      - status
      - refundStatus
      - updatedAt