This document describes the API backing the ECRS WebCart user interface. The WebCart API provides a robust and flexible framework for integrating and managing various WebCart functionalities in the eCommerce platform of your choice. This API enables developers to build custom e-commerce solutions by leveraging a wide range of endpoints that cover everything from user authentication and account management to order processing and inventory management.

In environments where multiple stores are served via a single domain name, a specific store can be selected by prefixing the given path with /s/{storeId} (ie., /s/1000-2/api/b).

Note that while ECRS attempts to maintain backwards compatibility whenever possible, this API is subject to change without notice.

Capabilities

The WebCart API is designed to empower integrators by providing a robust framework for building and managing e-commerce functionalities. The WebCart API enables you to:

• Authenticate Users: Manage user login and logout processes, including support for social logins and temporary one-time passwords (TOTPs).
• Manage Accounts: Retrieve and update customer account information, handle password resets, and manage account settings.
• Process Orders: Create, update, cancel, and query orders, ensuring efficient order management.
• Handle Payments: Accept various payment methods, including EBT and gift cards, and manage payment authorizations.
• View Inventory: Query item information, handle item recommendations, and manage item lists.
• Facilitate Customer Interactions: Manage customer notifications, handle customer check-ins, and process customer feedback through forms.
• Query Store Settings: Access store-specific configurations, themes, and styles.

Limitations

While the WebCart API offers extensive capabilities, there are some limitations to be aware of:

• Authorization Security: Account access to the API is managed through Authorization Security checkpoints. The WebCart API Access category includes comprehensive checkpoints, allowing you to have full control over which parts of the API users can access.
• Potential Dependency on API Keys: Third-party and machine account access to the API requires valid API keys, which must be securely managed.
• Potential Rate Limits: Some of the WebCart API endpoints are rate limited. These rate limits will be noted on the respective endpoints.

Applying Loyalty Points to a Transaction

This example demonstrates how to apply a loyalty tender to a cart and complete a transaction. Applying loyalty points requires an associated customer. Guest shoppers can use other tender types, but this example focuses on loyalty tenders. See the Authorization section for details on associating a customer

1. Create a Cart
   Issue a request to the Sync Cart endpoint with the shopper’s items to create a cart.

2. Select a Shipping Method
   Issue a request to the Sync Cart endpoint with the shopper’s shipping method selection. Once a shipping method is selected during the checkout process, relevant payment methods will be included in the cart response.

3. Find Loyalty Tenders
   Inspect the response from Sync Cart endpoint to discover which loyalty tenders are applicable.

   • type: 19 indicates a loyalty payment method.
   • balance: Total balance available in the loyalty account.
   • eligible: Amount that can be applied to the current transaction (may be less than the total if some items are ineligible).
   • methodId: Required for authorizing the loyalty tender. While pmID and methodId often share the same value, only methodId should be used when authorizing loyalty tenders. Using pmId may result in incorrect behavior or failed authorization. Example response:

     { 
      "checkout": { 
     "paymentMethods": [ 
         { 
             "available": true, 
             "balance": 99, 
             "eligible": 14.05, 
             "methodId": "1000-29006", 
             "name": "Default Loyalty Method", 
             "pmId": "1000-29006", 
             "provider": "ecrs-loyalty", 
             "testing": false, 
             "type": 19 
         } 
     ] 
      } 
     } 
     

4. Authorize Loyalty Tender
   Issue a request to the Authorize Payment endpoint with the desired amount.

5. Find Updated Total
   Issue a request to the Get Cart endpoint to get the updated due total.

6. Apply any additional tenders to bring the total due to zero
   Apply additional tenders as needed to cover any remaining balance. To complete the transaction, the total due must be 0.

7. Confirm the Transaction
   Complete the transaction using one of the following methods, depending on your checkout flow:

   • Send a request to the Confirm Checkout endpoint.
     • If using the Finalize Immediately Order Type, this action completes the transaction and processes loyalty rewards—redeeming existing points and awarding new ones based on the purchase.
     • Otherwise, loyalty points will be redeemed and rewarded when the transaction is completed at the point-of-sale.
     • Once the loyalty points are redeemed, they are removed from the customer's account.
   • Send a request to the Pay Now endpoint.
     • When using accelerated checkout, this option completes the transaction immediately, bypassing the point-of-sale.
     • This action processes loyalty rewards—redeeming existing points and awarding new ones based on the purchase.
     • Once the loyalty points are redeemed, they are removed from the customer's account.
   • Send a request to the Line Bust endpoint.
     • When using accelerated checkout, this option suspends the transaction, requiring completion at the point-of-sale.
     • Loyalty points will be redeemed and rewarded when the transaction is completed at the point-of-sale.
     • Once the loyalty points are redeemed, they are removed from the customer's account.

---

Current Revision: 5.8.183.15

5.8.183.15

Revision Date

• July 17, 2026

Breaking Changes

• Payment Authorization

  The Authorize Payment endpoint (POST /payauth/{method}/authorize) now rejects authorization requests for credit payment methods from guest shoppers, except when using Apple Pay or Google Pay.

5.8.183.1

#### Revision Date

03/20/2026

New

• Authorization

  The following endpoints can now return a new.social.account alert in the response when a new customer account is created via a federated/social login:

  • Verify Customer (POST /api/auth/verify)
  • OAuth Provider Login (POST /api/auth/provider/{provider})
  • Federated Login (POST /api/auth/federatedLogin/{provider})
  • Apple Login (POST /api/auth/appleLogin)
  • Facebook Classic Login (POST /api/auth/facebookLogin)

  This alert indicates that the shopper's account was newly created using a social network provider instead of the traditional registration process. Clients can use this alert to trigger a welcome experience or prompt the shopper to complete their profile. WebCart uses this alert to support shopper onboarding with email marketing and paperless receipt preferences.

• reCAPTCHA Source

  Two new Advanced Settings have been added to support custom reCAPTCHA site keys per source:

  • com.ecrsoft.tserver.webcart.recaptcha.siteKey.recaptchaSources - a comma-separated list of recognized recaptchaSource values.
  • com.ecrsoft.tserver.webcart.recaptcha.siteKey.<recaptchaSource> - the custom reCAPTCHA site key to use for the given <recaptchaSource> listed in the setting above.

  The following endpoints now accept a new recaptchaSource field. This field is the source mapped to the reCAPTCHA site key used to generate the reCAPTCHA token, and is used when a custom reCAPTCHA site key is configured:

  • POST api/auth/signup
  • POST api/auth/password
  • POST api/auth/provider/{provider}
  • POST api/auth/federatedLogin/{provider}
  • POST api/auth/appleLogin
  • POST api/auth/facebookLogin
  • POST api/ca/{id}/balance
  • POST api/cms/pay/{chargeType}
  • POST api/me/wallet/addToken
  • POST api/me/wallet/addEbtToken
  • POST api/payauth/{method}/authorize
  • POST api/contact

Fixes & Improvements

• Documentation improvements

  • Improved clarity and completeness of the documentation for Circulars and Accelerated Checkout endpoints.

• Account

  GET /me returns phone numbers with a new field, marketingState, that indicates the shopper's precise state in the consent flow.

• Store

  GET /configuration return new fields that dictate verbiage for text marketing prompts.

Fixes & Improvements

• Documentation Improvements

  • Improved clarity and completeness of the documentation for Circulars and Accelerated Checkout endpoints.

5.8.181.1

Revision Date

• 02/13/2026

New

• Authorization

  New endpoint - GET /api/auth/oauthCallback.html. Serves the OAuth callback HTML page used as a redirect URI to handle OAuth provider responses. This page receives the OAuth response from providers and communicates the result back to the parent window.

Fixes & Improvements

• Authorization

  • The following OAuth providers are no longer supported: LinkedIn, Twitter, Github, Instagram, Yahoo, and Microsoft Live.
  • A state and nonce variable must now be included in Federated and OAuth login requests.
  • A client attempting Federated Login must call the Generate Nonce endpoint prior to initiating the authorization request with the provider. The parameters returned by this endpoint must be passed to the provider in the authorization request, and passed to the WebCart API in the Federated Login endpoint.
  • The api/auth/storeNonce now accepts a stayLoggedInApple attribute in the request body. If true, a refresh token cookie will be returned when processing the request as an Apple Login

• Payment

  The api/payauth/{method}/authorize endpoint now respects the "Require customer checkout" checkbox from the WebCart profile in Web Office. If checked, this endpoint will return a 401 Unauthorized response when called as a guest.

• Push Notifications

  The api/push/sw.js endpoint has been changed to api/push/{platform}/sw.js where platform is either "pwa" or "non-pwa". This change is used to support better PWA push notification handling.

5.8.180.1

• Revision History for this document started with Revision 5.8.181. As such, revision history for older versions is not included here.

The endpoints in the Employee group are designed to manage employee-authenticated requests. These endpoints allow employees to perform actions with Employee-level privileges. Before users can utilize many of the endpoints in this group, they must complete either “Machine Account Login” or “Authenticate Employee.”

Machine Account users should start with a call to “Machine Account Login” (/employee/machineEmployeeLogin) to create a session.

All other users should start with a call to the “Authenticate Employee” (/employee/password) endpoint. This is the endpoint that is used by WebCart’s Employee Login, so users looking to make their own Employee Login would want to use the “Authenticate Employee” endpoint as well. Until the user has successfully performed the “Machine Employee Login” or “Authenticate Employee,” all the other endpoints in this group will return an error.

If the authenticated user has the necessary permissions, the next step is often to call “Associate as Customer” (/employee/cs), which permits performing actions on behalf of specific customers.

Use the endpoints in this group to:

• Retrieve a list of customers by accessing customer records.
• Allow an associated Employee to associate as a customer and perform operations on behalf of a customer.
• Retrieve system logs for troubleshooting and auditing purposes.
• Retrieve the current version number of the WebCart system.
• Verify employee credentials and allow users to log in as an employee.
• Replicate data from the CATAPULT database to WebCart.

Methods to manage customer push notification registration tokens and generate a service worker for Web Push. This includes methods to subscribe or unsubscribe registration tokens to specific topics. Customer association is required for all methods relating to registration tokens.

The Authorization endpoints provide comprehensive control over login authorization, allowing you to manage various aspects of user authentication and session management.
Use these endpoints to control how users can:

• Log into and out of WebCart. Choose how users can log in, either by username and password or through social login. An endpoint is also provided to verify credentials and offer a logout option.
• Interact with Temporary One Time Passwords (TOTPs). Generate, email, check, clear, and confirm TOTPs.
• Log into a Home Store. A Home Store is the default store a user is directed to upon login.
• Sign up for a new account, resend verification links, and request account removal.

Claims information:
WebCart sessions are persisted using cookies in the form of a JWT token. When an action requires the cookie to be updated, the response will contain two headers:

• flag-set-cookie: A flag set to 1 when the cookie has changed.
• set-cookie: Contains a copy of the new cookie with the JWT token filled with claims information.
  The cookie is HttpOnly. If it is necessary to access to the claims from JavaScript, a copy of the claims in the cookie can be retrieved at any time from the Get Customer Claims endpoint. When the flag-set-cookie header appears, it is best practice to pull the new claims and update any relevant client-side values.
  
  

Possible JWT claims include:

• "disp": Display name.
• "num": Customer number.
• "emp": Employee claim.
• "emn": Employee name associated with the claim.
• "pl": Price level of the claim.
• "pf": Customer power field of the claim.
• "lym": Loyalty multiplier of the claim.
• "cart": Active cart ID in cpk-pk format.
• "ordertype": Order type of the claim in cpk-pk format.
• "cart-ot-": Cart order type in cpk-pk format appended to the field, with the value being the cart cpk-pk (e.g., ["cart-ot-1000-4": "0-6374"]).
• "home": Home store.
• "ep": Boolean indicating whether an email is provided.
• "spp": Special pricing claim.
• "tpr": Timeout period.
• "dispShort": Nickname if provided, otherwise first name, or account number if neither exist.
• "scango": Boolean indicating whether the user is in Accelerated Checkout mode. Refer to Accelerated Checkout
• "macc": Boolean indicating whether the JWT is for a machine account.
• "fi": Fraud iterator (deprecated).
• "iss": Issuer (always "com.ecrs.ecat").
  

OAuth Login

To authenticate with Third Party OAuth and obtain a Refresh Token, see the OAuth Provider Login endpoint.

The endpoints in this group allow shoppers to reset their passwords. Here is an overview of the steps involved.

1. Obtain a key (UUID) by calling the Forgot Password endpoint. This will send a verification code to the shopper by email, text, or call.
2. When the shopper enters the verification code, submit both the code and the key to the Verify Shopper endpoint to receive a reset token.
   • If multiple matching accounts are found, prompt the shopper to select an account and submit the code, key, and user ID to Verify Selected Account. This situation is uncommon, and the verification code is only valid for a single account, so this does not permit changing the password for an account the shopper does not control.
3. Before prompting the shopper to enter a new password, validate the reset token with the Validate Token endpoint to ensure it has not expired.
4. Submit the new password and reset token to the Reset Password endpoint to change the password.