← Back to Blogs
by

How to Call the Retail Pro Prism API: Version 1 and Version 2

Retail Pro Prism is the POS and retail management platform behind thousands of specialty retail stores worldwide. If you are building an integration with an e-commerce platform, ERP, WMS or analytics tool, sooner or later you will need to read or write data in Prism through its REST API.

Prism's API has more than one generation, and the differences matter in practice. This guide walks through how to authenticate and call both version 1 and version 2, and how to avoid the most common pitfalls.

First, know how Prism's API is deployed

There is no central cloud endpoint. Prism is installed per customer, so the API lives on each retailer's own Prism server, usually on their local network or private infrastructure. Two consequences follow:

  • You call your customer's server, for example http://prism-server/..., not a public URL.
  • Resources and fields can differ between Prism versions and between customer installations. Never assume one customer's schema is identical to another's.

Every Prism server ships with an API Explorer, reachable in a browser at /api-explorer on the server. It lists the services and resources available on that specific installation and is the best place to confirm field names before you write code.

Version 1: the /v1/rest endpoints

The version 1 API lives under /v1/rest, with resources such as customers, documents and inventory. For example:

GET http://prism-server/v1/rest/customer

To discover the fields of a resource, append /meta/ after the resource name:

GET http://prism-server/v1/rest/customer/meta/

Authenticating against v1

Version 1 uses the original three-step handshake, known as Auth, Sit and Stand:

  1. Auth. You make a first call and the server answers with a challenge (a nonce).
  2. Sit. You answer the challenge with the user name and password for your Prism account. If it succeeds, the server returns a session token.
  3. Stand. When you are finished, you close the session.

For every later request you send the session token in the Auth-Session header. The exact calculation used to answer the challenge is described in Retail Pro's developer documentation for your Prism version, so follow that document rather than copying a snippet from a forum.

Version 2: the /api endpoints

The newer API is organised by service under /api. For example, common resources are under /api/common/, such as:

GET http://prism-server/api/common/employee

Version 2 also supports introspection. Adding ?introspection=true returns the structure of a resource, so you can see its fields without guessing:

GET http://prism-server/api/common/employee?introspection=true

Use the API Explorer to see which other services are available on your server, such as back-office resources for customers, inventory and receipts.

Authenticating against v2 (Prism 2.3 and later)

Prism 2.3 introduced a simpler login endpoint:

GET /api/security/login?usr=<user>&pwd=<password>&ws=<workstation>&claimseat=true&appid=<your-app-name>

The main parameters are:

  • usr and pwd: the Prism user and password. Retail Pro's own example shows the password in hashed form, so check the documentation for your version on how it must be sent.
  • ws: the workstation name that identifies the calling machine or application.
  • claimseat: true for a seated, read-write session, false for a non-seated session.
  • appid: a name that identifies your application.

A successful login returns a session payload. From then on, send the session value in the Auth-Session header on every call:

GET /api/common/employee
Auth-Session: <session value from login>

When you are done, call /api/security/logout with the same header. Do not hold up your process waiting for the logout response.

Prism 2.3 still supports the older Auth, Sit and Stand security endpoints for a limited time, mainly so existing customizations keep working. New projects should use the login endpoint.

Seats and licensing: an important detail

Starting with Prism 2.3, how you log in affects licensing:

  • An application that only reads data can use a non-seated session.
  • An application that creates or changes data needs a read-write connection, which takes a licensed seat.
  • Restarting the Prism server invalidates active session tokens, so your integration must be ready to log in again.

Plan for this early, because a leaked or unclosed seated session can block a real store user from logging in.

Version 1 vs. version 2 at a glance

Version 1 Version 2
Base path /v1/rest/... /api/... (for example /api/common/...)
Discover fields /meta/ after the resource ?introspection=true
Authentication Auth, Sit, Stand handshake /api/security/login (2.3 and later)
Session header Auth-Session Auth-Session
Best for Existing integrations and older servers New projects on current Prism versions

Best practices for production integrations

  • Check the version first. Confirm the customer's Prism version before choosing v1 or v2.
  • Use the API Explorer and metadata. Read field names from the server itself instead of hard-coding assumptions.
  • Use a dedicated API user with only the security permissions the integration needs.
  • Always log out and reuse sessions where you can, rather than logging in for every call.
  • Handle expired sessions. If a call is rejected because the session is no longer valid, log in again and retry.
  • Page through large result sets and avoid pulling the whole catalogue in one request.
  • Test against a non-production server first, especially before writing data.

The connectivity challenge: Prism lives on a local network

Because most Prism servers are only reachable from inside the retailer's network, a cloud platform cannot call them directly. This is the exact situation AllSync offline connectors are built for. An offline connector installed on a local server can log in to Prism, read data through the v1 or v2 API, and send it to AllSync, where it can be mapped and delivered to Shopify, your ERP, or any other system, and the reverse flow works too.

Conclusion

Calling the Prism API comes down to three steps: find out which version your server runs, authenticate the right way (Auth, Sit and Stand for v1, the login endpoint for v2), and send the Auth-Session header on every call. Use the API Explorer and metadata to confirm each resource's shape, respect licensing seats, and always close your sessions.

Need to connect Retail Pro Prism with your online channels? Talk to us about integrating it with AllSync.

← Previous PostNext Post →