Gift cards and store credit

Gift cards and store credit both hold value a customer can spend at the register. A gift card belongs to a serial number, so whoever has the card can use it. Store credit belongs to a customer, so the customer has to be on the sale. This guide shows how each one gets value, how it's spent and how to manage it through the API.

In the app

• Product → Gift Cards lists your gift cards. You can create one, or open one by its serial number.
• Admin → Reason Codes holds your gift card and store credit reasons. Each reason is linked to a ledger account.

Gift cards

How a gift card gets its value

• Sold at the register or through the API. Selling a gift card product creates the card. The line's serial_number becomes the card's serial, and the line's price becomes its value. Leave the serial empty and Smooth POS makes up a 16-character one. If the serial already exists, the sale is rejected with giftcard already exists.
• Issued directly. Create a gift card with POST /giftcard.json, for example as a goodwill gesture or when you move cards from another system.

{
  "serial": "GC-000123",
  "initial_amount": 50,
  "reason": "Goodwill",
  "customer_email": "[email protected]"
}

• Leave out serial and one is generated for you.
• Leave out expiration and Smooth POS sets a default expiry date. Send one if you need a specific date.
• customer_email links the card to the customer with that email. You can send customer_id instead.
• reason and account_id record why the card was issued and which ledger account it's linked to. Use one of your gift card reasons (see List gift card reasons).

A serial that's already taken fails with gift card already exists.

Look cards up

• Get a gift card by serial: GET /giftcard/{serial}.json. Note it's giftcard, singular.
• List gift cards with filters such as serial, customer_id, min_current_amount and the expiration range. Each card has initial_amount, current_amount and expiration.

Change the expiry date

Update a gift card with PUT /giftcard.json. Send the card's serial and the new expiration. It changes the expiry date (and custom fields), not the balance.

{"serial": "GC-000123", "expiration": "2027-12-31T23:59:59Z"}

How a gift card is spent

At the register, a gift card is a payment. Through the API, send a payment that uses your gift card payment method and carries the card's serial in serial_number. The amount comes off current_amount, and the payment fails if the card doesn't have enough on it. A negative gift card payment (a refund) puts the value back on the card.

Store credit

Every customer has a credit_balance. Credit goes on and comes off in three ways:

Adjust store credit

Adjust store credit with POST /storecredit/adjust.json:

{"customer_id": 2099268, "amount": -25, "reason": "Goodwill", "account_id": 412}

🚧

The sign is the other way round

amount is how much credit comes off the customer's balance. A negative amount adds credit and a positive amount removes it. The example above gives the customer 25 of credit.

• account_id is the ledger account for the other side of the entry, usually the account on the matching store credit reason (see List store credit reasons). Smooth POS posts a "Store Credit Adjustment" journal between it and your store credit account.
• You can't take a balance below zero. That fails with failed to update store credit.
• The response is the updated customer.

See the history

List a customer's store credit transactions returns every movement, oldest first. Here the sign is the familiar way round: negative amounts are credit spent and positive amounts are credit issued. sale_id and payment_id link each movement to its sale.

React to changes in Glue

Example: Email a customer when you issue them credit

Trigger: System Hook, storecredit_adjust.

1. Script: Read the adjustment

   JavaScript

   var adj = JSON.parse($.default);
   $.customer_id = adj.customer_id;
   $.credit_added = adj.amount < 0;
   $.credit_amount = Math.abs(adj.amount);

2. If Condition: If credit was added, Condition $.credit_added === true. Under THEN:

   1. API Request: Get a customer for customer {{ customer_id }}, Response variable customer_res.

   2. Script: Read the customer

      JavaScript

      $.customer = JSON.parse($.customer_res.body);
      $.has_email = !!$.customer.email;

   3. If Condition: If the customer has an email, Condition $.has_email === true.

   4. Email: Tell the customer, nested under that THEN: To {{ customer.email }}, Template Custom, Subject You've got store credit, Body <p>Hi {{ customer.first_name }}, we've added {{ credit_amount }} of store credit to your account.</p>

Remember that storecredit_adjust sends the adjustment's own sign, so a negative amount means credit was added.