Orders & Rewards

POS Integration / Core Concepts

Orders & Rewards

There are 4 elements to the LevelUp Ordering & Rewards process:

  1. Applying external (non-LevelUp) discounts and tenders
  2. Applying LevelUp Rewards as a discount
  3. LevelUp Gift Card credit and tips as a tender &/or gratuity
  4. Applying LevelUp payment and tips as a tender &/or gratuity

Apply External Discounts and Tenders

Always apply other (non-LevelUp) discounts and tenders first. This may include cash, credit, coupons or any other form of discount or tender outside the LevelUp system.

Applying Rewards and Gift Cards

LevelUp offers many ways for merchants to offer loyalty rewards to their customers and it’s very helpful for these rewards to be reflected in their POS system. When completing an integration with LevelUp payments, applicable credit can be retreived and applied to the check as a discount before applying the final tender. This credit application should also provide the benefit of automatically adjusting the tax due on the check once it has been applied.

There are two basic steps in applying realtime credit to a check. The first step is to create a proposed order. This endpoint takes all the relevant details about an order and returns the discount amount to apply and a proposed order UUID. The second step is to complete the order by creating a completed order.

Credit should be applied in the following order:

1) Non-LevelUp coupons or discounts

2) LevelUp credit (as a discount)

Once you’ve applied the above credits/discounts, you’re ready complete the proposed order.

Ensure you are passing the full amount (spend_amount) you’d like to tender to LevelUp. This is typically the check balance plus any LevelUp discounts applied to this order (with the exception of split payments). The spend amount should only be adjusted between calls to reflect the decrease in tax (when discounts are applied).

Simple Example

Check total = $20 + $1 tax.

{
  "proposed_order": {
    "payment_token_data": "LU02000008ZS9OJFUBNEL6ZM030000LU",
    "cashier": "Bob",
    "exemption_amount": 0,
    "receipt_message_html": null,
    "register": "3",
    "tax_amount": 100,
    "identifier_from_merchant": "001001",
    "partial_authorization_allowed": true,
    "location_id": 19,
    "spend_amount": 2100,
    "items": [{ ... }]
  }
}

Proposed order response indicates $5 LevelUp rewards credit (discount_amount) should be applied to this check/order:

{
  "proposed_order": {
    "discount_amount": 500,
    "uuid": "1b3b3c4d5e6f7g8a9i9h8g7f6e5d4c3b2a1"
  }
}

1) Apply the $5 credit (discount_amount) as a discount (new check total: $15 + $.75 tax)

2) Send a completed order request with a $20.75 spend_amount param (calculated based on $15 check balance to be tendered + $.75 as adjusted tax + $5 discount applied) and a $5 applied_discount_amount:

{
  "completed_order": {
    "applied_discount_amount": 500,
    "cashier": "Bob",
    "exemption_amount": 0,
    "identifier_from_merchant": "001001",
    "location_id": 1234,
    "partial_authorization_allowed": true,
    "payment_token_data": "LU02000008ZS9OJFUBNEL6ZM030000LU",
    "proposed_order_uuid": "1b3b3c4d5e6f7g8a9i9h8g7f6e5d4c3b2a1",
    "receipt_message_html": "Pick up your order at <strong>counter #4</strong>",
    "register": "03",
    "spend_amount": 2075,
    "tax_amount": 75,
    "items": [{ ... }]
  }
}

3) Receive response w/ approved amount of $20.75 + $2.75 tip

{
  "order": {
    "gift_card_total_amount": 1000,
    "gift_card_tip_amount": 0,
    "spend_amount": 2075,
    "tip_amount": 275,
    "total_amount": 2350,
    "uuid": "5a1z9x2h31ah7g8a9i9h8g7f6e5d4c4a21o"
  }
}

4) Apply $10 gift card amount as LevelUp gift card tender (new check total due: $5 + $0.75 tax + $2.75 tip = $8.50)

5) Apply $8.50 as LevelUp tender, which should apply the $2.75 as gratuity/overage

6) Close the check

Credit and Tender Application FAQ

Call Timeouts

If the call to check rewards fails (timeout), simply retry until it succeeds. Do not attempt to tender with “0” or NULL values.

Applying Credit(s)

Apply LevelUp merchant-funded credit as a discount (so tax is automatically adjusted)
Note: you may need to manually refresh the check to update the tax due
Merchant-funded credit cannot be applied to gratuity
Merchant-funded credit cannot be applied to tax

Applying Tender(s)

Only apply LevelUp gift card credit (as “LevelUp Gift Card Tender”) AFTER you’ve received an approved LevelUp completed order
Gift card credit can be applied to gratuity
Gift card credit can be applied to tax
Once you’ve applied merchant-funded credit and gift card credit, the rest should be tendered to a LevelUp tender type
Make sure you apply gratuity if it is returned from the LevelUp tender request