LiquiDonate ReturnsDirect By LiquiDonate (Beta) API

openapi: 3.2.0
info:
  title: ReturnsDirect By LiquiDonate (Beta) API
  version: 1.0.0-beta
  summary: 'Returns management integration: push order data to LiquiDonate and receive return and refund status webhooks.'
  description: ReturnsDirect by LiquiDonate integrates LiquiDonate as a returns management solution for an ecommerce platform, retail brand or custom returns portal.
  contact:
    name: LiquiDonate
    url: https://docs-returns.liquidonate.com
    email: sales@liquidonate.com
  termsOfService: https://www.liquidonate.com/terms-of-service
  x-source: https://docs-returns.liquidonate.com
  x-source-collection: https://documenter.getpostman.com/view/28612413/2sBXierZMP
  x-lifecycle: beta
  x-generated-by: api-evangelist enrichment pipeline
  x-generated: '2026-07-19'
servers:
- url: https://returns.liquidonate.com
  description: Production.
- url: https://returns-sandbox.liquidonate.com
  description: Sandbox, documented as the integration base URL.
security:
- shopDomain: []
  hmacSignature: []
tags:
- name: ReturnsDirect By LiquiDonate (Beta)
paths: {}
webhooks:
  returnStatusChanged:
    post:
      operationId: onReturnStatusChanged
      summary: Return status event
      description: Sent to your registered webhook URL when a return moves to pending, pending_approval, approved, rejected or cancelled. Signed with the same HMAC-SHA256 scheme; verify with a timing-safe comparison.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnWebhookEvent'
            example:
              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'
      responses:
        '200':
          description: Acknowledged.
      tags:
      - ReturnsDirect By LiquiDonate (Beta)
  refundStatusChanged:
    post:
      operationId: onRefundStatusChanged
      summary: Refund status event
      description: Sent to your registered webhook URL when a refund completes or is flagged for review.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnWebhookEvent'
            example:
              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-07T10:30:00.000Z'
      responses:
        '200':
          description: Acknowledged.
      tags:
      - ReturnsDirect By LiquiDonate (Beta)
components:
  schemas:
    ReturnWebhookEvent:
      type: object
      description: Outbound return/refund status event sent by ReturnsDirect to the retailer webhook URL.
      properties:
        event:
          type: string
          enum:
          - return.pending
          - return.pending_approval
          - return.approved
          - return.rejected
          - return.cancelled
          - refund.completed
          - refund.flagged
        shop:
          type: string
          description: Your shop identifier.
          example: acme.com
        parcelId:
          type: integer
          example: 101
        rmaId:
          type: string
          example: '1001'
        externalOrderId:
          type: string
          example: order_99001
        orderNumber:
          type: string
          example: '#1001'
        status:
          type: string
          enum:
          - pending
          - pending_approval
          - approved
          - rejected
          - cancelled
        refundStatus:
          type: string
          enum:
          - pending
          - completed
          - flagged
        refundAmount:
          type: number
          nullable: true
        refundMethod:
          type: string
          example: cash
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    shopDomain:
      type: apiKey
      in: header
      name: X-Shop-Domain
      description: Your shop identifier, e.g. acme.com. Must match the value LiquiDonate has on file.
    hmacSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: HMAC-SHA256 of the raw request body using the shared secret LiquiDonate provisions for your shop, as lowercase hex.