Connecting Heartland Retail takes three steps: sign in to Heartland from Wrapped and allow access, turn the sales channel on, and make sure Heartland has three gift card adjustment reason codes named Correction, Gift and Promotional. Wrapped uses Heartland's own gift cards, so staff keep selling, redeeming and refunding to gift cards in Heartland as they do today, and every card stays in step with Wrapped and your other channels.
Before you start
- You need to be an Owner or Admin in Wrapped.
- Turn on gift cards in Heartland Retail. Wrapped works with Heartland's built-in gift cards.
- Sign in to Heartland with a user who can authorise apps for your Heartland account.
Step 1: Connect Heartland Retail
- In Wrapped, go to Settings › Sales channels (open) and select Add sales channel.
- Choose Heartland Retail.
- Sign in to Heartland Retail and select Allow.
- You're returned to Sales channels with the message "Heartland Retail connected."
- Turn on the switch next to your Heartland channel. It starts Disabled.
When you connect, Wrapped adds a webhook to Heartland so it's told each time a sale is completed. You don't need to set this up.
Step 2: Create the gift card adjustment reason codes
Heartland needs a reason for every gift card Wrapped creates and every balance Wrapped changes. Wrapped looks for three reasons by name.
- In Heartland Retail, go to Settings › Reason Codes › Gift Card Adjustments.
- Make sure these three reasons exist, and add any that are missing: Correction, Gift, Promotional.
| Reason | When Wrapped uses it |
|---|---|
| Gift | Creating a gift card in Heartland, for example one issued from the dashboard or sold on your web store |
| Promotional | Creating a promotional gift card, such as a bonus gift card from an automation |
| Correction | Changing a gift card's balance in Heartland, including setting it to $0 when a card is voided or deleted |
The names must match (capital letters don't matter). If one is missing, Wrapped can't create or update gift cards in Heartland, and the gift card shows a sync error such as "Gift card reason 'Promotional' needs to be added to your Heartland settings". Add the reason, then open the card and choose Re-sync balance to sales channels from the … menu.
Gift card codes in Heartland
Heartland removes dashes and other symbols from gift card numbers and stores letters as capitals, so a Wrapped code abcd-1234 becomes ABCD1234 in Heartland. To keep codes identical everywhere, we recommend turning off Add a dash every four characters in Settings › Gift card rules › Code format before you start issuing gift cards (see Gift card code format and each platform's rules). Changing the format only affects new cards.
What syncs
| What happens in Heartland | Result in Wrapped |
|---|---|
| A gift card is sold on a completed ticket | The card is created in Wrapped with its Heartland number and made available in your other channels. If a customer with an email address is on the ticket, the card is emailed to them. |
| More funds are added to an existing card on a completed ticket | A top-up is recorded |
| A gift card is used to pay on a completed ticket | The redemption is recorded and the new balance goes to your other channels |
| A return is refunded onto a new or existing gift card | The refund is added to the card (or a new card is created) |
| A ticket is voided | Nothing. Wrapped only processes completed tickets. If you void a gift card sale, void the card in Wrapped too (see Void or delete a gift card). |
| What happens in Wrapped or another channel | Result in Heartland |
|---|---|
| A gift card is issued | Created in Heartland with the same code (reason Gift or Promotional) |
| A balance changes | Adjusted in Heartland (reason Correction) |
| A gift card is voided or deleted | Balance set to $0 in Heartland (reason Correction) |
Only tickets completed after you connected are processed. Sales usually reach Wrapped within a few minutes.
To correct a balance, adjust it in Wrapped rather than in Heartland, so every channel stays in step (see Adjust a gift card's balance).
Test the connection
- In Wrapped, go to Gift cards › All gift cards, select Issue gift card, and issue a small gift card. Copy the code.
- Wait a minute, then look the code up in Heartland (for example, start a sale, choose the gift card payment method and look the card up). You should see the balance you issued.
- Don't complete the sale.
- Delete the test card in Wrapped (… menu › Delete gift card). Wrapped sets its balance to $0 in Heartland.
If the card isn't in Heartland, open it in Wrapped and look for a sync error. A missing reason code is the most common cause.
Common questions
We already have gift cards in Heartland. Will they work with Wrapped?
They aren't imported automatically. The Wrapped team can import your active Heartland gift cards so they work in every channel (see Getting help). Until a card is in Wrapped, spending it in Heartland doesn't update Wrapped.
Do I need a gift card product in Heartland?
No. Wrapped recognises gift cards from the ticket itself: a gift card line or a gift card payment.
Is there a Settings or Test connection option for Heartland?
No. Heartland has no extra settings in Wrapped. Use Check orders on the channel to see what Wrapped did with recent tickets (see Sales channel status).
The connection stopped working. How do I reconnect?
Repeat step 1 with the same Heartland account. Wrapped refreshes the existing channel, turns it on and reinstalls the webhook.