Panasonic POS integration

This guide is for Panasonic engineers connecting a Panasonic POS to Spoonity loyalty and promotions. The POS sends Spoonity each check. Spoonity works out the discounts and returns them item by item. When the check closes, Spoonity records the sale in the customer's loyalty account.

The POS never calculates a Spoonity discount, never chooses a reward, and never calls any other Spoonity API. Three calls cover the whole integration: check, close and void.

Base URL: https://panasonic.spoonity.com

Contents

1. Status
2. The flow
3. Authentication
4. Identifiers
5. The check: items, modifiers and combos
6. POST /partners/pos/check
7. Applying the discounts
8. POST /partners/pos/close
9. POST /partners/pos/void
10. Repeating calls safely
11. Timeouts and failures
12. Errors
13. Testing
14. Checklist

1. Status

Until an item is live, what this guide says about it is the contract we are building to.

2. The flow

1. Before the till. The customer opens the merchant's app and picks the reward they want to use. The app tells Spoonity directly. The POS is not involved and never sees a list of rewards.
2. Scan. At any point while the order is being taken, the cashier scans the customer's code from the app. The POS recognises it as a Spoonity code by its prefix (see Identifiers) and holds it on the check. No call is made at scan time.
3. Pay Now. The POS sends the whole check to POST /partners/pos/check with the scanned code. Spoonity finds the customer and the reward they picked, applies the merchant's promotions, holds the reward for this check, and returns each discount with the item it applies to.
4. Cancel and change. If the cashier cancels out of Pay Now, the POS removes the Spoonity discounts. No call is needed. When Pay Now is pressed again, the POS sends check again with the full new check, and that answer replaces the previous one.
5. Close. When the check is paid and closed, the POS sends POST /partners/pos/close. Spoonity answers at once, so the POS can finish. Spoonity then posts the sale to the loyalty program in the background: the customer earns points and the reward is used up.

Send check and close for every check, including checks with no code scanned. A check with no code is priced for a guest: promotions open to everyone still apply, and no points are earned.

Customer app        POS terminal                    Spoonity
     |                    |                              |
     | pick a reward ---------------------------------->| saved for today
     |                    |                              |
     | show code -------->| scan: code held on check     |
     |                    | Pay Now: POST /check ------->| find the pick, price, hold
     |                    |<-----------------------------| discounts by item
     |                    | cancel, change, Pay Now:     |
     |                    | POST /check ---------------->| re-price, replace
     |                    |<-----------------------------| discounts by item
     |                    | apply discounts, take payment|
     |                    | check closed: POST /close -->| commit, answer at once
     |                    |<-----------------------------| { committed: true }
     |                    |                              | post sale to loyalty

3. Authentication

Send the merchant's API key as a bearer token on every request:

Authorization: Bearer MERCHANT_API_KEY

• Spoonity provides the key when the merchant is set up. The key decides the merchant; a merchant id in the body is never read.
• The base URL and the key are the only settings that change per merchant.
• A missing or unknown key is 401 UNAUTHORIZED.
• X-Spoonity-POS-Key: MERCHANT_API_KEY is also accepted, for POS software that cannot set Authorization.
• Keep the key in POS configuration, never in logs or receipts.
• Content-Type: application/json on every request. Unknown fields are rejected with 400, so a misspelled field is never silently ignored.

4. Identifiers

Recognising a Spoonity code. Spoonity codes start with a fixed prefix that Spoonity gives you during setup. Configure the POS to treat any scanned code with that prefix as a loyalty code. What follows the prefix is Spoonity's business: the POS sends the whole code and never interprets it.

5. The check: items, modifiers and combos

All money is integer cents (1149 is $11.49) and before tax. A decimal is a 400. Spoonity does not calculate tax.

Items. One line per item on the check: { line_id, sku, name?, price, quantity, categories?, modifiers?, discounts? }.

• line_id is unique within the check. Use the same ids on every check for that check and on close.
• sku is the item's PLU.
• price is the unit price the item sold at, without modifiers.

Modifiers. List each modifier on the item it belongs to, with its own unit price and quantity: { id, name?, price, quantity }. A modifier with no charge has price: 0.

Combos. Send a combo as one line with its parts in components:

Spoonity splits the combo price across the parts in proportion to their a la carte prices, and the parts always add up to the combo price exactly. A reward on a part inside a combo takes off that part's share of the combo price, not its a la carte price.

Your own discounts. Discounts the POS already applied (employee, senior, manager) go on the line as discounts: [{ id, name?, amount }], whole-line cents. By default Spoonity does not add its own item discount to a line you already discounted, and order-level discounts are calculated after yours, so the same money is never discounted twice.

Limits (a request over any of them is a 400):

• 200 lines per check, 2000 units per check (each part of a combo counts), 1 to 1000 units per line. Leave a line off rather than sending quantity: 0.
• Any single amount at most 100,000,000 cents, never negative.
• Per line or part: at most 50 modifiers, 50 categories, 50 discounts and 50 components.
• Ids are 1 to 128 characters, name fields at most 256.

6. POST /partners/pos/check

Send when Pay Now is pressed, and again every time Pay Now is pressed after a change.

Example: a combo with a large drink, and a cookie. The customer picked a free taters reward in the app, and the merchant runs $5 off checks of $12 or more.

{
  "check_id": "20261103-104202",
  "store_id": "1042",
  "terminal_id": "02",
  "customer": { "customer_id": "SPN6040123412341234" },
  "lines": [
    { "line_id": "101", "sku": "2PCCOMBO", "name": "2 Pc Combo", "price": 1149, "quantity": 1,
      "components": [
        { "component_id": "101-1", "sku": "2PC", "name": "2 Pc Chicken", "price": 899, "quantity": 1 },
        { "component_id": "101-2", "sku": "TATERS", "name": "Taters", "price": 399, "quantity": 1 },
        { "component_id": "101-3", "sku": "FOUNTAIN", "name": "Fountain Drink", "price": 279, "quantity": 1,
          "modifiers": [{ "id": "LRG", "name": "Large", "price": 50, "quantity": 1 }] }
      ] },
    { "line_id": "102", "sku": "COOKIE", "name": "Cookie", "price": 199, "quantity": 1 }
  ]
}

Response 200:

{
  "evaluation_id": "1042:20261103-104202",
  "check_id": "20261103-104202",
  "customer": {
    "customer_id": "2114003",
    "balances": [{ "currency_id": "loyalty", "balance": 4200 }]
  },
  "subtotal": 1398,
  "subtotal_discount": 791,
  "total": 607,
  "discounts": [
    { "pos_reference": "SPN-FREETATERS", "offer_id": "reward_free_taters", "name": "Free Taters (reward)",
      "amount": 291, "scope": "item", "line_id": "101", "component_id": "101-2", "quantity": 1 },
    { "pos_reference": "SPN-5OFF", "offer_id": "promo_5_off", "name": "$5 off $12",
      "amount": 500, "scope": "order",
      "allocations": [
        { "line_id": "101", "component_id": "101-1", "amount": 296 },
        { "line_id": "101", "component_id": "101-3", "amount": 114 },
        { "line_id": "102", "amount": 90 }
      ] }
  ],
  "offers": [
    { "offer_id": "reward_free_taters", "name": "Free Taters (reward)", "status": "applied",
      "source": { "type": "redemption", "vendor_perk_redemption_id": 501 },
      "pos_reference": "SPN-FREETATERS", "discount_total": 291 },
    { "offer_id": "promo_5_off", "name": "$5 off $12", "status": "applied",
      "source": { "type": "promotion_code" }, "pos_reference": "SPN-5OFF", "discount_total": 500 }
  ],
  "receipt_lines": ["Free Taters (reward) applied, you saved $2.91", "$5 off $12 applied, you saved $5.00"],
  "redemption_id": "ored_5a58c78e-fbb4-4674-8bc5-827d72884dea",
  "hold_expires_at": "2026-11-03T17:45:00.000Z"
}

• subtotal is the check before discounts. subtotal_discount is the sum of every Spoonity discount. total is subtotal, minus your own line discounts, minus subtotal_discount. All before tax.
• offers[] lists every offer the merchant has and what happened to it: applied, applicable (would apply if selected), skipped or inapplicable. An offer that did not apply has a reason with a stable code (for example MIN_SPEND_NOT_MET, RESERVED, LOCALLY_DISCOUNTED) and a message a cashier can read.
• receipt_lines are ready to print. Treat them as display text: the wording can change.
• customer is null when no code was scanned or the code is not recognised. The check is then priced with the promotions open to everyone.
• hold_expires_at: the customer's reward is held for this check until then (15 minutes), so it cannot be used at another store at the same time. If payment is not finished by then, send check again.
• external_discount_total appears only when you sent your own line discounts.

7. Applying the discounts

Every Spoonity discount is applied to an item, so tax is calculated on the discounted item. There can be more than one Spoonity discount on a check.

• scope: "item": apply amount to the line line_id, or to the combo part component_id of that line when it is present.
• scope: "order": apply each entry in allocations to its line (and combo part) for that entry's amount. The allocations always add up to the discount's amount.

How the POS represents the discount is up to you. One generic "Spoonity Discount" item, sold as a negative-priced modifier on the item it discounts, works for every Spoonity discount. You do not need an item per offer. pos_reference identifies the offer for close and for reporting.

8. POST /partners/pos/close

Send once the check is paid and closed, for every check, even when check failed, timed out or was never sent.

Example, for the check above:

{
  "check_id": "20261103-104202",
  "store_id": "1042",
  "pos_transaction_id": "1042-20261103-104202",
  "terminal_id": "02",
  "closed_at": "2026-11-03T12:36:10-05:00",
  "receipt": {
    "lines": [
      { "line_id": "101", "sku": "2PCCOMBO", "name": "2 Pc Combo", "price": 1149, "quantity": 1,
        "components": [
          { "component_id": "101-1", "sku": "2PC", "name": "2 Pc Chicken", "price": 899, "quantity": 1 },
          { "component_id": "101-2", "sku": "TATERS", "name": "Taters", "price": 399, "quantity": 1 },
          { "component_id": "101-3", "sku": "FOUNTAIN", "name": "Fountain Drink", "price": 279, "quantity": 1,
            "modifiers": [{ "id": "LRG", "name": "Large", "price": 50, "quantity": 1 }] }
        ] },
      { "line_id": "102", "sku": "COOKIE", "name": "Cookie", "price": 199, "quantity": 1 }
    ],
    "discounts": [
      { "pos_reference": "SPN-FREETATERS", "amount": 291, "line_id": "101", "component_id": "101-2" },
      { "pos_reference": "SPN-5OFF", "amount": 296, "line_id": "101", "component_id": "101-1" },
      { "pos_reference": "SPN-5OFF", "amount": 114, "line_id": "101", "component_id": "101-3" },
      { "pos_reference": "SPN-5OFF", "amount": 90, "line_id": "102" }
    ],
    "total": 607
  }
}

Response 200:

{ "committed": true, "redemption_id": "ored_5a58c78e-fbb4-4674-8bc5-827d72884dea", "evaluation_id": "1042:20261103-104202" }

Spoonity answers before it posts the sale to the loyalty program, so close stays fast. The POS does not need to wait for, or check, the loyalty side.

If what you applied differs from what check returned, Spoonity still commits (the money has already left the till) and reports the difference in a mismatch object with the expected and received references and totals.

committed: false is still a 200, so the POS never retries it. The reason says why:

9. POST /partners/pos/void

Optional. Use it if the merchant's POS can cancel a check after check, or refund a sale that had Spoonity discounts. Partial refunds are not supported.

{ "check_id": "20261103-104202", "store_id": "1042", "pos_transaction_id": "1042-20261103-104202" }

Response 200:

{ "voided": true, "redemption_id": "ored_5a58c78e-fbb4-4674-8bc5-827d72884dea", "evaluation_id": "1042:20261103-104202", "state": "rolled_back" }

• Open check (state: "cancelled"): the hold is released and the customer's reward is available again. You do not need this for a cancel out of Pay Now: the next check replaces the previous answer.
• Closed check (state: "rolled_back"): the reward and any usage limits are restored, and Spoonity reverses the sale in the loyalty program.
• state: "expired": the hold had already ended, so there was nothing to release.
• An unknown check answers { "voided": false, "redemption_id": null, "reason": "NO_PENDING_EVALUATION" }.

10. Repeating calls safely

• check can be repeated. The same check_id and store_id always refer to the same check, and each call replaces the previous answer. If the new check no longer qualifies, the held reward is released.
• close can be repeated with the same pos_transaction_id. A retry gets the same answer and nothing is committed or posted twice.
• void can be repeated with the same pos_transaction_id. A void may use the same transaction id as the close.
• A closed check cannot be checked again (409 CHECK_CLOSED). A new sale needs a new check_id.
• After 10 restarts of one check (holds that expired, or voids while open), check answers 409 CHECK_REOPEN_LIMIT; use a new check_id.

11. Timeouts and failures

• Never block the cashier on Spoonity. If check times out, returns a 5xx or fails on the network, close the check without a Spoonity discount.
• Timeout. Spoonity aims to answer check in under 300 ms. Your existing loyalty timeout works; a shorter one makes the cashier wait less when something is wrong.
• Always send close, even after a failed or skipped check. It is how Spoonity records the sale and posts the customer's points. A close that never arrives means the customer earns no points for that sale.
• Retrying close. Both close and void are safe to repeat. If the POS can retry them on a 5xx or network error, it should. If it cannot, close is still sent once and the cashier moves on.
• Do not retry a 4xx except 409 OFFERS_RESERVED (once).

12. Errors

Error bodies are { "error": { "code": "...", "message": "..." } }.

13. Testing

Spoonity provides a test merchant and its API key on https://panasonic.spoonity.com, with a test customer code and rewards set up for the scenarios below.

1. Guest check with no code: check, then close.
2. Code scanned, reward picked in the app: discount returned on the right item and applied, close commits.
3. Reward on a part of a combo: discount lands on that part.
4. Order discount: allocations applied to their items and add up.
5. Cancel out of Pay Now, change the order, Pay Now again: the second check replaces the first.
6. Spoonity unreachable: the check closes without a discount, and close is still sent.
7. Modifiers with and without a charge.
8. A POS discount (employee or manager) on a line next to a Spoonity discount.

14. Checklist

• Base URL and merchant API key in POS configuration, key sent as Authorization: Bearer.
• Spoonity code prefix configured as a loyalty code.
• check_id is YYYYMMDD-<order number>.
• check sent at every Pay Now, with the whole check.
• Combos sent with components; modifiers on their item or part.
• Every Spoonity discount applied to its item or part.
• close sent for every check, with the discounts actually applied.
• Amounts in integer cents, before tax.

For AI coding assistants

This guide is also available as plain markdown at /docs/index.md, and as one file at /docs/llms-full.txt. An index for language models is at /llms.txt.