@nwhau/pos-giftcards

Convert REX (from Shopify POS Tile) gift cards into native Shopify physical gift cards with seamless cashier flow.

🧩 Overview

The @nwhau/pos-giftcards module enables integration between Retail Express (REX) and Shopify POS.
It allows cashiers to convert a REX gift card into a native Shopify physical gift card directly during checkout.

Once a customer is selected (or the system defaults to a cash sale customer), the conversion triggers an app flow named convert-rex-gift-card, completing the migration automatically.

This package simplifies hybrid POS environments, ensuring a unified customer experience and reducing manual reconciliation.

⚙️ Installation

npm install @nwhau/pos-giftcards
# or
yarn add @nwhau/pos-giftcards

🧠 Usage Example

Below is an example of using the module in a Shopify POS extension:

import { useExtensionApi } from '@shopify/ui-extensions-react';
import { convertRexGiftCard } from '@nwhau/pos-giftcards';

export default function ConvertRexGiftCardButton() {
  const api = useExtensionApi();

  const handleConvert = async () => {
    const payload = {
      ShopifyGiftCardCode: '4RMIIQNGZ9728M2C',
      RexGiftCardCode: '38301',
      amount: 5,
      customer_id: 6805489614914,
    };

    await convertRexGiftCard(api, payload);
  };

  return (
    <Button onPress={handleConvert}>
      Convert REX Gift Card
    </Button>
  );
}

When executed, this triggers the flow:

[[extensions]]
name = "NWH Convert REX Gift Card"
handle = "nwh-convert-rex-gift-card"
type = "flow_trigger"
uid = "8324df42-a986-e9cf-5d5e-xxxx"

Once completed, the cashier continues the transaction as normal — using the Shopify gift card through the native POS flow.

🧰 API Reference

convertRexGiftCard(api, payload)

Converts a REX gift card into a Shopify gift card.

| Parameter | Type | Required | Description | |------------|------|-----------|-------------| | api | ExtensionApi | ✅ | Shopify POS Extension API instance | | payload | object | ✅ | Contains gift card and customer details | | payload.ShopifyGiftCardCode | string | ✅ | Shopify gift card code | | payload.RexGiftCardCode | string | ✅ | REX gift card code | | payload.amount | number | ✅ | Amount to transfer | | payload.customer_id | number | ✅ | Shopify customer ID |

🧾 Example Flow Trigger in shopify.extension.toml

[[extensions]]
name = "NWH Convert REX Gift Card"
handle = "nwh-convert-rex-gift-card"
type = "flow_trigger"
description = "Triggers when a REX gift card is converted to Shopify"

🧱 Build Commands

# Build
npm run build

# Clean dist folder
npm run clean

# Watch mode for development
npm run dev

🚀 Publishing Workflow

1. Login and Build

npm login
npm run build

2. Publish a Beta Version

Used for internal or testing releases.

npm version prerelease --preid=beta
npm publish --tag beta

This will publish under the beta dist-tag:

@latest -> 0.1.1
@beta   -> 0.1.2-beta.0

3. Publish a Release Candidate

For final testing before a stable release:

npm version prerelease --preid=rc
npm publish --tag rc

Creates a version like 0.1.2-rc.0 published under @rc.

4. Publish a Stable (Latest) Release

Once tested and verified:

npm version patch    # or minor / major
npm publish --tag latest

🔁 Promoting Between Lanes

If a beta or rc build is approved for production, promote it to latest without republishing:

# Promote an existing rc build to latest
npm dist-tag add @nwhau/[email protected] latest

You can list and manage all tags with:

npm dist-tag ls @nwhau/pos-giftcards
npm dist-tag rm @nwhau/pos-giftcards beta

🧩 Example Version Flow

| Stage | Command | Resulting Tag | Example Version | |--------|----------|---------------|-----------------| | Development | npm publish --tag beta | beta | 0.1.2-beta.0 | | Candidate | npm publish --tag rc | rc | 0.1.2-rc.0 | | Stable | npm publish --tag latest | latest | 0.1.2 |

🪪 License

MIT © NWH

💬 Support

For issues or feature requests, please open a GitHub issue or contact support via internal channels.