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.

There are various use cases for users accessing the WebCart API; however, users typically fall into one of two categories:

1. An integrator using WebCart's API and creating their own user interface ("head"). Because this route does not require third-party accounts to access the API, it does not depend on API keys, nor does it require the use of Authorization Security checkpoints.

Example: A CATAPULT retailer wishes to create their own app with custom UI specific to their unique branding.

2. A user authorizing a third-party to perform an operation on their behalf using the WebCart API. This approach requires the CATAPULT retailer to generate an API key for the integrator and set up an Employee / Authorization Security appropriately. More information on how to grant Machine Account access to the API in CATAPULT Web Office is available in the OLM.

Example: A CATAPULT co-op wishes to manage their customers’ membership information and fees via a third-party. Any third-party acting as an employee to perform tasks (such as updating membership details) will need explicit permissions set at a granular level to make changes to the CATAPULT database.

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.

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. This includes methods to subscribe or unsubscribe registration tokens to specific topics. Customer association is required for all methods.

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, two values are set in the header:

• 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. You can get a copy of the claims in the cookie at any time from the Get Customer Claims endpoint. Best practice is to pull the new cookie and set relevant values on the client side when the flag-set-cookie value is present in the header.
  
  Possible JWT claims:
• "disp": Display name.
• "num": Customer number.
• "emp": Employee claim.
• "emn": Employee name on 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 if the email is provided.
• "spp": Special pricing claim.
• "tpr": Timeout period.
• "dispShort": Nickname if provided, or first name if provided. If neither exist, the account number.
• "scango": Boolean indicating if the user is in Accelerated Checkout mode. Refer to Accelerated Checkout
• "macc": Boolean indicating if the JWT is for a machine account.
• "fi": Fraud iterator (deprecated).
• "iss": Issuer, always "com.ecrs.ecat".

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.

Endpoints in this group control store-specific options, allowing users to access information set on the Web Profile for the store in Web Office. This includes:

• Returning a blank page, custom source details, header scripts, the Web App Manifest (for PWA installation), store detail objects, style.css, and .well-known files.
• Submitting a Contact Us form.
• Returning the store’s configuration, including site URL, substitution policies, accessibility disclaimers, and features like cart and list functionalities.