Third-Party Aggregator Authentication Method

TPAs have access to both Client Credentials authentication and OAuth 2.0 Auth Code Flow (with optional PKCE) for authentication and authorization of their integration. Please see Authorization Methods for details.

The following scopes are available with Client Credentials authentication:

• location.read
• product.read
• notification.read
• notification.write

The following scopes are available with Auth Code Flow (i.e., a user token present):

• account.read
• product.read
• pricing.read
• order.read
• order.write
• location.read
• notification.read
• notification.write
• offline_access

Third-Party Aggregator Integration Setup

You will need to sign up for our ABC Supply Partner Developer Portal to gain access to our API Sandbox and Production environments. See Developer Portal User Guide to complete the sign-up process, gain access to our API Sandbox environment, and for additional information about requesting Production access once your integration development is complete.

Your Sandbox environment is configured with access to the following test user account to assist with building and testing your integration:

Username: [email protected]

Password: Test@123

NOTE: You will not be able to access any real ABC Supply customer accounts in the Sandbox environment.

Third-Party Aggregator Integration Best Practices

Use Client Credentials to Configure Platform Data Access

Client Credentials for Aggregators can be used to configure webhooks, ingest the complete ABC Supply product catalog, and/or offer branch location look-up within your platform. For all other API functionality, you will use Auth Code Flow, which requires a user and user token to be present to send and receive API requests.

The following sections require Auth Code Flow and a user to be connected within your platform.

Determine Account Access

In Sandbox and Production, you will find ABC customer accounts available to the user using the Account API. We recommend using Search Accounts endpoint and querying by “accountType” equal to "Ship-To". This will list all Ship-To accounts to which the user has access, as well as a list of branches to which their Ship-To accounts have access.

NOTE: Because branches determine their own product catalogs and pricing, it is best practice to have the user select a Ship-To account and branch before allowing them to select items and view pricing.

Browse or Search For Products

Once you have account and branch access information, products and their branch availability can be retrieved using Product API. Several endpoints offer optional branch availability data embedding; please see individual endpoint documentation for details.

With the exception of the Get All Items endpoint, the Product API endpoints do not return item data for items that are not available at any branch to which the current user has access. Requests made for these items will return errors in the Product API endpoints.

To ingest the complete ABC Supply product catalog, please use the Get All Items endpoint with Client Credentials authentication.

Item Pricing

To retrieve pricing for an item from the Price Items endpoint, the item must be available at a branch to which your current user’s ABC Supply customer account has access. Pricing will reflect any ABC Supply level or contract pricing active on the Ship-To account provided in the request. To make a pricing request, the following fields are required:

• ABC Supply customer Ship-To account number
• ABC Supply branch number
• item bumber
• quantity
• unit of measure (optional)

If no unit of measure is provided, the Price Items endpoint will return pricing for the item based on the internal ABC Supply “stocking” unit of measure, which will appear in the response. For additional information about the Price Items endpoint, please refer to the endpoint documentation.

Placing Material Orders

The Place Orders endpoint is used for sending a digital order to ABC Supply. The request will include Ship-To account, branch number, delivery details, and line item details and optional order comments. Please be aware that several validations are completed on the request prior to sending the request to ABC Supply; therefore, it is highly recommended to take note of the possible errors that might occur. A successful order placement will return a 201 ACCEPTED response with a confirmation number in the response body. This is confirmation number can be used to track the order.

When an order is placed, an order acknowledgement email is sent to the designated recipients in myABCSupply.com for the customer account and the order is sent to the designated branch in ABC Supply’s order management system. The order is remains in a "Requested" state until the branch accepts or rejects the order. During this time, the Get Order Details endpoint will not return order information for the order. Once the order is Accepted by the branch, it is submitted to the ERP system and Get Order Details will return a successful response.

Order Tracking

Order Status webhooks are the best method for order tracking. Any change to an order will send an Order Status webhook payload to your registered webhook. Please refer to the Order Update Event documentation for additional information.

Order details can be retrieved using the order number or confirmation number of an order from Get Order Details once the order has been accepted by the ABC Supply branch and submitted to the ERP system.

Invoices

The Order Invoiced webhook will deliver new invoices with invoice details in JSON format for orders placed through the integration only. Please refer to the Order Invoiced Event documentation for additional information.