Return

For installation instructions, see Getting Started with Unify Widgets.

Basic Implementation

As a dialog (default)

<unify-return-widget
  api-key="your-api-key"
  order-id="your-order-id"
></unify-return-widget>

<button onclick="document.querySelector('unify-return-widget').open = true">
  Return items
</button>

Inline (no dialog)

<unify-return-widget
  api-key="your-api-key"
  order-id="your-order-id"
  no-dialog
></unify-return-widget>

Component Attributes

Attribute	Type	Required	Description
`api-key`	String	Yes	API key for Unify requests
`order-id`	String	Yes	Order identifier to fetch returnable products
`open`	Boolean	No	Controls dialog visibility when dialog mode is enabled
`no-dialog`	Boolean	No	Renders content inline instead of inside a dialog
`demo`	Boolean	No	Enables demo mode (`X-Demo-Mode: true` header)

Component Properties

Property	Type	Required	Description
`config`	Object	No	Configuration object (see Config Options)

Config Options

Pass configuration via the config property to customize text labels and behavior.

document.querySelector('unify-return-widget').config = {
  dialogTitle: 'Manage returns',
  locale: 'en-US',
  hidePrice: false,
  // ... more options
};

Dialog & Layout

Option	Default	Description
`dialogTitle`	`"Returns"`	Title for the returns dialog

Return Process

Option	Default	Description
`toReturnTitle`	`"Products to Return"`	Header for returnable products section
`toReturnDescription`	`"Please provide the quantities and reasons for each product you wish to return."`	Description text
`returnedTitle`	`"Returned Products"`	Header for previously returned items
`noProductsToReturn`	`"No products to return"`	Message when no returnable products exist
`selectReasonLabel`	`"Select a reason"`	Placeholder text for reason dropdown
`returnReasonLabel`	`"Return Reason:"`	Label for return reason selector
`ctaLabel`	`"Submit"`	Submit button label
`submittingLabel`	`"Submitting..."`	Loading state button text

Product Display

Option	Default	Description
`colorLabel`	`"Color:"`	Product color attribute label
`sizeLabel`	`"Size:"`	Product size attribute label
`hidePrice`	`false`	Hide product prices in display
`locale`	`"en-US"`	Locale for price and date formatting

Return History & Documents

Option	Default	Description
`trackingNumberLabel`	`"Tracking Number:"`	Label for tracking number
`legalMentions`	`""`	Legal disclaimer text shown below form
`documentLabelReturnSlip`	`"Return Slip:"`	Label for return slip documents
`documentLabelShippingLabel`	`"Shipping Label:"`	Label for shipping label documents
`documentLabelReturnLabel`	`"Return Label:"`	Label for return label documents

The API may return other document types. Each type uses a documentLabel<TypeInPascalCase> config key, falling back to the type name formatted as a title. For example, a document of type "customs_form" uses documentLabelCustomsForm and defaults to "Customs Form:".

Error Handling & Messaging

Option	Default	Description
`errorMessage`	`"Error loading data"`	Generic error message
`dataFetchError`	`"Unable to load return information."`	Error when fetching data fails
`returnsNotEnabledError`	`"Returns are not available."`	Error when returns not enabled
`noValidReturnProducts`	`"Please select at least one product with a return reason"`	Validation error when no products selected
`errorSubmittingReturn`	`"Unable to submit return"`	Error when return submission fails
`returnSubmittedSuccessfully`	`"Your return request has been submitted successfully!"`	Success message after submission

Auto-Refresh

Option	Default	Description
`refreshAfterReturnTimer`	`-1`	Milliseconds to wait before auto-refreshing data after submission (set to -1 to disable)

Styling

CSS Custom Properties (recommended)

All visual tokens (colors, sizes, spacing, fonts) are exposed as CSS custom properties prefixed with --unify-. This is the stable styling API.

Set them on the widget element or any ancestor:

unify-return-widget {
  --unify-confirm-button-bg: #dc3545;
  --unify-confirm-button-color: white;
  --unify-confirm-button-hover-bg: #c82333;
  --unify-dialog-bg: #ffffff;
  --unify-product-border-color: #e0e0e0;
  --unify-alert-success-bg: #d4edda;
  --unify-alert-error-bg: #f8d7da;
}

To discover all available properties:

Open browser DevTools
Inspect the <unify-return-widget> element
Look at the Computed tab for all --unify-* entries
Edit them live in the Styles panel to preview

Alert state colors:

--unify-alert-success-* (success alerts)
--unify-alert-error-* (error alerts)
--unify-alert-warning-* (warning alerts)
--unify-alert-info-* (info alerts)

CSS Parts

Structural elements can be targeted using ::part():

unify-return-widget::part(dialog) {
  border-radius: 12px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.15);
}

unify-return-widget::part(product) {
  border-radius: 8px;
}

unify-return-widget::part(dialog-confirm) {
  border-radius: 6px;
}

Common parts:

dialog — main dialog container
dialog-header — dialog title
product — individual product card
product-image — product image
product-details — product info
product-name, product-price, product-size, product-color — product fields
product-options — return reason selector container
return-reason-select — reason dropdown
to-return-product-list — returnable items container
returned-product-list — previously returned items container
dialog-confirm — submit button
alert — alert containers (with modifiers: alert--success, alert--error, alert--warning, alert--info)

⚠️ Parts may change between versions. Use CSS custom properties where possible.

Events

`dialog-opened`

Fired when the dialog open/close state changes.

document.querySelector('unify-return-widget').addEventListener('dialog-opened', (event) => {
  console.log('Dialog is', event.detail.open ? 'open' : 'closed');
});

Detail shape:

{
  open: boolean  // true when opened, false when closed
}

Examples

Styled with custom theme

<style>
  unify-return-widget {
    /* Submit button */
    --unify-confirm-button-bg: #ff5722;
    --unify-confirm-button-color: white;
    --unify-confirm-button-hover-bg: #e64a19;
    
    /* Dialog styling */
    --unify-dialog-bg: #fafafa;
    --unify-dialog-color: #212121;
    --unify-backdrop-bg: rgba(0, 0, 0, 0.7);
    
    /* Product cards */
    --unify-product-border-color: #e0e0e0;
    --unify-product-bg: #ffffff;
    --unify-product-border-radius: 8px;
    
    /* Alerts */
    --unify-alert-success-bg: #c8e6c9;
    --unify-alert-success-color: #2e7d32;
    --unify-alert-error-bg: #ffcdd2;
    --unify-alert-error-color: #c62828;
  }
</style>

<unify-return-widget
  api-key="your-api-key"
  order-id="your-order-id"
></unify-return-widget>

Handling the return workflow

const widget = document.querySelector('unify-return-widget');

widget.config = {
  dialogTitle: 'Manage your returns',
  toReturnTitle: 'Which items would you like to return?',
  selectReasonLabel: 'Why are you returning this?',
  submittingLabel: 'Processing your return...',
  legalMentions: 'Returns must be initiated within 30 days of purchase. Items must be unworn and in original packaging.',
  refreshAfterReturnTimer: 3000,  // Auto-refresh after 3 seconds
};

// Track when user opens returns
widget.addEventListener('dialog-opened', (event) => {
  if (event.detail.open) {
    analytics.track('return_dialog_opened', {
      order_id: widget.getAttribute('order-id')
    });
  }
});

// Programmatically open/close
function initiateReturn() {
  widget.open = true;
}

function closeReturn() {
  widget.open = false;
}