Upvendo Knowledge Base

Appearance

Shopcaisse Integration Setup ​

Looking for guided setup? Start Emily in the backoffice for step-by-step guided setup.

Purpose ​

The Shopcaisse integration connects Upvendo to Shopcaisse POS systems. It enables merchants to pull their existing product catalog from Shopcaisse into Upvendo and push orders back to Shopcaisse after payment is confirmed. This allows businesses to accept orders via Upvendo channels (Kiosk, Online Ordering) while Shopcaisse remains the central POS for in-store operations and fulfillment.

Production status: Live end-to-end verified 2026-06-04 (order push, kitchen lifecycle, fiscal finalization, sale recording, VAT application). Available for non-French merchants. French (NF525) market is gated on a separate compliance audit.

Key Concepts ​

Shopcaisse API and Authentication ​

Shopcaisse uses a REST API with JWT-based authentication. Each Shopcaisse API application is linked to a JWT token (called an AppToken) that defines the access level and permissions for the integration. The token is structured around four main resource types:

  • Stores -- physical store locations
  • Products -- the product catalog (items, categories)
  • Orders -- order management
  • Customers -- customer records and loyalties

Each resource supports sub-resources and granular permissions (read, write, delete). The bearer token provided during setup encodes all the necessary permissions for Upvendo to read products and write orders.

Shopcaisse API Environments ​

Shopcaisse provides two API environments:

  • Staging -- for testing and development
  • Production -- for live operations

Ensure you use the correct bearer token for the environment you intend to connect to.

Location-Specific Scope ​

Each Shopcaisse connection is tied to a single Upvendo location. If a merchant has multiple stores in Shopcaisse, each store must be connected to its own Upvendo location with the corresponding bearer token.

One-Way Menu Sync (Shopcaisse to Upvendo) ​

Menu items must exist in Shopcaisse before connecting. Upvendo cannot create items in Shopcaisse -- it only reads the existing catalog. The sync imports:

  • Products with names, prices, and identifiers
  • Categories and product groupings
  • Variants and modifiers if configured in Shopcaisse

Order Forwarding (Upvendo to Shopcaisse) ​

After payment is confirmed via Viva Wallet (Kiosk) or Stripe (Online Ordering), Upvendo forwards the order to Shopcaisse. The order includes item references, quantities, and payment confirmation details.

Webhook Notifications ​

Shopcaisse supports webhooks that can notify Upvendo of internal changes (e.g., product updates, price changes). When registered, Shopcaisse sends notifications to a configured webhook URL whenever relevant data changes in the POS.

Data Mapping ​

When products are imported from Shopcaisse, the following mapping applies:

ShopcaisseUpvendoNotes
StoreLocationOne-to-one mapping via bearer token
Product CategoryCategoryGroups items in the Upvendo menu
ProductItemThe sellable entity with name, price, and identifiers
Product VariantModifier / VariantOptional size or option selections
CustomerCustomer recordUsed for loyalty and order history

API Versioning ​

Shopcaisse versions its API with each new breaking release. Ensure the bearer token corresponds to the current API version. Check the Shopcaisse developer documentation for version-specific changes that may affect the integration.

OpenAPI Specification ​

Shopcaisse provides an OpenAPI (Swagger) specification for its Public API. Each API request is documented with required permissions, request schemas, response schemas, and example payloads. This specification is useful for verifying the data format when troubleshooting sync issues.

Resource and Permission Model ​

The Shopcaisse API uses a hierarchical resource and permission model:

  • Resources follow the pattern MAIN_RESOURCE_TYPE.RESOURCE_ID (e.g., stores.12345)
  • Permissions follow the pattern MAIN_RESOURCE_TYPE.SUB-RESOURCE.NODE (e.g., products.*.read)
  • The wildcard * grants access to all sub-resources within a main resource type
  • Each bearer token encodes the exact set of resources and permissions available to the integration

Actions ​

Connect Shopcaisse ​

Route: /shopcaisse

  1. Complete all prerequisites (see checklist below — both Upvendo-side and Shopcaisse-side)
  2. Select the target location from the topbar
  3. Click Connect or Add Channel and select Shopcaisse
  4. Enter your Shopcaisse bearer token (the JWT AppToken from your Shopcaisse External Application). The backoffice path is Features → Integrations → Connectors & API → Public API → Configure → Your External Applications — the older "Settings → External Applications" path no longer exists.
  5. Store selection — Upvendo validates the token and lists every Shopcaisse store covered by the JWT's resources. If the token covers:
    • One store: it's auto-bound to this Upvendo Location (no manual step).
    • Multiple stores: you'll see a picker. Select which Shopcaisse store maps to this Upvendo Location. Each Location must be bound to exactly one store; if you have multiple physical locations, repeat this flow for each.
  6. Click Sync Now to pull menu items from Shopcaisse
  7. Verify the sync completed successfully in the Shopcaisse Logs

Sync Menu ​

Route: /shopcaisse

Click Sync Now to manually trigger a full product import from Shopcaisse. The sync reads the product catalog via the Shopcaisse API and maps it to Upvendo categories and items. The sync process:

  1. Authenticates with the Shopcaisse API using the stored bearer token
  2. Fetches all product categories from the connected store
  3. Fetches all products with their variants and pricing
  4. Maps Shopcaisse categories to Upvendo categories
  5. Maps Shopcaisse products to Upvendo items with prices and identifiers
  6. Updates the Shopcaisse Logs with sync results (items imported, errors encountered)

Review Imported Menu Items ​

After sync:

  1. Go to Menus -> Items (/menus/items)
  2. Review the menu items pulled from Shopcaisse
  3. Make any necessary adjustments (prices, descriptions, images)
  4. Items that do not exist in Shopcaisse will not appear -- all items must originate from the POS

Test Connection ​

After entering credentials, use the test function (if available) or trigger a small sync to verify API connectivity. Check the Shopcaisse Logs for confirmation that the API responded successfully.

Delete Integration ​

Remove the Shopcaisse integration to disconnect the location. This clears the bearer token and removes the sync link. Imported menu items remain in Upvendo but will no longer sync.

Configure Webhook (Optional) ​

If you want Upvendo to be notified when products change in Shopcaisse:

  1. Log in to your Shopcaisse account
  2. Go to the API application settings
  3. Register Upvendo's webhook URL for your application
  4. Shopcaisse will send notifications when products, prices, or categories change

Business Rules ​

  • Menu items must exist in Shopcaisse POS before they can appear in Upvendo. There is no push from Upvendo to Shopcaisse for product data.
  • Orders are only forwarded to Shopcaisse after payment is confirmed via Viva Wallet (Kiosk) or Stripe (Online Ordering).
  • The bearer token must have the correct permissions: at minimum, read access to stores and products, and write access to orders.
  • Each Upvendo location connects to one Shopcaisse store. Multiple stores require multiple location connections.
  • If the Shopcaisse API is unreachable when an order is placed, the order is queued and retried when the connection is restored.
  • The bearer token is a JWT and does not expire in the traditional sense, but it can be revoked from the Shopcaisse application settings. If revoked, a new token must be entered in Upvendo.
  • Shopcaisse is location-specific: the bearer token is tied to a specific store's resources and permissions.
  • The wildcard * in Shopcaisse permissions grants access to all sub-resources within a resource type. Ensure the token scope is appropriately restricted for security.
  • Product variants in Shopcaisse are mapped to modifiers or item variants in Upvendo, preserving size and option selections.
  • After disconnecting, imported menu items remain in Upvendo but will no longer receive updates from Shopcaisse. You must manually maintain items or reconnect to resume sync.

Prerequisites Checklist ​

Before integrating with Shopcaisse, complete these steps in order:

1. Payment Profile Setup (Required) ​

  1. Go to Settings -> Payments (/settings/payments)
  2. Set up your payment providers:
    • Viva Wallet for Kiosk payments (terminal-based)
    • Stripe for Online Ordering payments
  3. Configure payment methods

2. Billing Profile Setup (Required) ​

  1. Go to Settings -> Billing (/settings/billing)
  2. Complete your billing information

3. Branding Profile Setup (Required) ​

  1. Go to Settings -> Brand (/settings/brand)
  2. Configure your store's branding (logo, colors, etc.)

4. Location Creation (Required) ​

  1. Go to Settings -> Locations (/settings/locations)
  2. Create your location with:
    • Business name and address
    • Business hours
    • Contact information
  3. Select this location from the topbar before connecting Shopcaisse

5. Shopcaisse Account Setup (Required) ​

Before generating a bearer token, the merchant must satisfy all of the following on their Shopcaisse account. Each one is a gate — skipping any will cause a specific, visible failure.

#RequirementCostFailure mode if skipped
aPublic API subscription active under Features → Integrations → Connectors & API → Public API€19.99 / month + VATNo External Application can be created; nothing to paste into Upvendo
bOrder Management Module activated on each POS device (paid add-on, per device — activated in the POS/Cash register app or the corresponding backoffice Apps section)Paid; per-devicePOST /orders returns HTTP 401 — "Pos {id} does not have an Order Management Module license! Please activate the module in the POS/Cash register in order to receive orders". Orders cannot be received.
cExit Discovery Mode (click "Start collecting payments" on the yellow banner, if present)Free, one-timeThe iPad app blocks "Track open orders" with "feature not available in demo mode". Orders queue up in not_acked indefinitely.
diPad POS app installed, logged in, running, onlineFreeNo device to consume the incoming-orders queue → orders stall in not_acked even with all other prerequisites met.
eMenu fully configured in Shopcaisse (items, modifiers, VAT codes)FreeUpvendo cannot create items in Shopcaisse; the catalog must originate there.

6. Obtain Shopcaisse Bearer Token (Required) ​

  1. Log in to bo.shopcaisse.com
  2. Navigate to Features → Integrations → Connectors & API → Public API → Configure (the older "Settings → External Applications" path no longer exists)
  3. In the "Your External Applications" dialog, click the + tile to create a new application
  4. Fill in:
    • Name: e.g. "Upvendo Integration"
    • Webhook URL: https://api.upvendo.com/api/webhook/shopcaisse (production) or your reseller's webhook URL
    • Resource list: select the Company and the Store(s) to grant access. POS scope is auto-included under the selected store.
  5. Save. The application card will show the JWT token — copy it.
  6. Ensure the token grants at minimum:
    • company.*.items.* (catalog read/write)
    • store.*.orders.* (order create/read/write)
    • store.*.sales.read (for reconciliation)
    • store.*.stocks.read (for inventory sync, future)

Order Flow ​

Orders are created in Upvendo (via Kiosk or Online Ordering) and pushed to Shopcaisse after payment is confirmed.

Kiosk Flow ​

text
Customer submits order on Kiosk
            |
Payment terminal (Viva Wallet) prompts for payment
            |
Customer pays the prompted amount
            |
Upvendo receives successful payment webhook
            |
Order confirmed and pushed to Shopcaisse via API

Online Ordering Flow ​

text
Customer submits order online
            |
Payment processed (Bancontact redirect or card details via Stripe)
            |
Customer pays the prompted amount
            |
Upvendo receives successful payment webhook
            |
Order confirmed and pushed to Shopcaisse via API

FAQs ​

Q: After I paste the JWT, I see a list of stores — what is this? A: This is the store selection step. A single Shopcaisse External Application JWT can cover multiple stores (everything in its resource list). Upvendo asks which one this particular Upvendo Location maps to. If your JWT only covers one store, this step is skipped automatically.

Q: My orders arrive but show "Order has not been paid" on the iPad — what's wrong? A: This was a known bug (fixed in production June 2026) where payment amounts were sent in cents but Shopcaisse expected decimal euros, causing a 100× mismatch. If you see this on an integration that hasn't been updated, force a re-sync or contact support. On current installations the math balances and the order shows as "Paid" automatically.

Q: Orders arrive but stay in "not_acked" forever — what's wrong? A: One of the three iPad-side gates is missing on the merchant's Shopcaisse account: (a) Order Management Module not activated on the POS (verify in the POS app's Apps/features section), (b) account still in Discovery Mode (yellow "Start collecting payments" banner is visible), or (c) iPad POS app isn't running / not connected. Walk through prerequisites a / b / c in the Shopcaisse Account Setup section above.

Q: Why do my "test orders" never show up in /sales or revenue? A: Shopcaisse explicitly blocks testOrder: true orders from fiscal finalization — they cannot become sales by design (NF525 fiscal-archive safety). Upvendo always sends testOrder: false for real merchant orders so this only affects integration testing.

Q: Can I create menu items in Upvendo and push them to Shopcaisse? A: Only for simple items. A plain item you create in Upvendo can be pushed back to Shopcaisse (it needs a resolvable VAT rate and a token with item-write permission). Anything structural — modifier groups, formulas/menus, packs, product variants, images — cannot be pushed: Shopcaisse only lets those be created on the iPad POS app. The practical rule stays the same: build your menu structure in Shopcaisse, sync it into Upvendo, and treat Shopcaisse as the source of truth for the catalog.

Q: What permissions does the bearer token need? A: At minimum, the token needs read access to stores and products (to pull the menu) and write access to orders (to push orders). The permissions are defined in the AppToken's resource and permission configuration in Shopcaisse.

Q: What happens if the bearer token is revoked? A: The integration will fail to sync or push orders. Go to /shopcaisse, enter a new valid bearer token, and reconnect.

Q: Does the integration support inventory/stock tracking? A: Stock management depends on the Shopcaisse API capabilities and the token permissions. Check the Shopcaisse Logs for stock-related sync results.

Q: Can I connect the same Shopcaisse store to multiple Upvendo locations? A: No. Each Shopcaisse store should be connected to exactly one Upvendo location. Using the same token for multiple locations may cause order routing issues.

Q: Is this integration production-ready? A: This integration is currently under development/testing. Consult the Upvendo team before using it in a production environment.

Q: Does Shopcaisse support webhooks? A: Yes. Shopcaisse can send notifications to Upvendo when internal data changes (e.g., product updates, price changes). Webhook registration is configured in the Shopcaisse API application settings.

Q: How do I get a bearer token from Shopcaisse? A: Log in to your Shopcaisse account, go to API application settings, create or select an application, configure the required resource permissions, and copy the generated JWT token.

Q: What API environments does Shopcaisse offer? A: Shopcaisse provides two environments: Staging (for testing) and Production (for live operations). Make sure your bearer token matches the environment you intend to use.

Q: How do I check what permissions my bearer token has? A: The bearer token is a JWT that encodes resource access and permissions. You can decode it using a tool like jwt.io to inspect the resources and permissions fields. Ensure it includes read access to stores and products, and write access to orders.

Q: Can I use the same bearer token for multiple Upvendo locations? A: Only if the token grants access to the store resources for all locations. However, it is recommended to use a separate token per store for clearer permission boundaries.

Troubleshooting ​

Orders or items not syncing ​

  • Check the Shopcaisse bearer token is valid and has not been revoked
  • Verify the Shopcaisse system is online and the API is reachable
  • Check Shopcaisse Logs for sync errors
  • Ensure the token has the correct permissions for the resources being accessed

"401 Unauthorized" or "403 Forbidden" error ​

  • The bearer token may have been revoked or may lack the required permissions
  • Log in to Shopcaisse and verify the API application token is still active
  • Check that the token includes the necessary resource permissions (stores, products, orders)
  • Generate a new token if needed and re-enter it in Upvendo
  • Verify the Shopcaisse store has products configured
  • Check that the bearer token has read access to the products resource (products.*)
  • Ensure you are using the correct environment (Staging vs Production) token
  • Review the Shopcaisse Logs for specific error messages

Orders not appearing in Shopcaisse ​

  • Verify the order was paid successfully (orders are only pushed after payment confirmation)
  • Check that the bearer token has write access to the orders resource (orders.*)
  • Review the Shopcaisse Logs for order push errors
  • If the Shopcaisse API was temporarily unavailable, the order may be queued for retry

"Invalid token" or JWT errors ​

  • The bearer token may be malformed or from the wrong Shopcaisse environment
  • Ensure you copied the complete token string without any truncation
  • Verify the token is from the correct environment (Staging or Production)
  • Generate a new token from the Shopcaisse API application settings

Webhook notifications not arriving ​

  • Check that the webhook URL is correctly registered in the Shopcaisse API application
  • Verify the Upvendo webhook endpoint is accessible from the internet
  • Review Shopcaisse's webhook delivery logs for failed notifications

Prices differ between Shopcaisse and Upvendo ​

  • Menu prices are imported at sync time. If prices changed in Shopcaisse after the last sync, run Sync Now to pull updated prices
  • Check if the Shopcaisse store has any location-specific pricing overrides that may not be reflected
  • Verify the correct tax rate is applied to items in both systems

Products missing after sync ​

  • Check if the products are active in Shopcaisse (inactive products may be excluded from the API response)
  • Verify the bearer token has permission to access all product categories
  • Review the Shopcaisse Logs for any items that were skipped due to missing required fields (name, price)
  • If the store has a large catalog, the sync may take longer -- check the logs for completion status