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.

Current Revision: 5.7.158.15

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 endpoints in the Authorization group control login authorization. With these endpoints, you can manage all options related to signing into and out of WebCart.

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.

The endpoints in this group control password reset options. Use these endpoints to:

• Allow users to request a password reset.
• Select a method of receiving their password reset authorization code. Users can choose to receive the code via email, text, or call.
• Send and verify the secure code before allowing a password update.
• Allow a user to choose a new password, enforce minimum password requirements, and update the customer account to include the new 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.