Search Items

Product API

Search the ABC Supply product catalog for items using different search criteria. Get product information with optional features such as same-family items and branch availability.

Product API

POST /search/items

Search for items based on specific product attributes

Sandbox

Resource:

POST

https://partners-sb.abcsupply.com/api/product/v1/search/items

Production

Resource:

POST

https://partners.abcsupply.com/api/product/v1/search/items

Authorization

OAuth 2.0 server or user token with the product.read scope.

Request

Filtering Options

To make a search request, use the filters[].condition value of “contains”. Available types for searching are “longDescription” and “itemNumber”.
To make a filter request, use the filters[].condition value of “equals”. Available types for filtering are “itemNumber”, “branchNumber”, and “productFamilyId”.

Two filters objects can be provided to create a search or filter on multiple criteria.

Additional Options

To embed branch availability for each item returned in the search, include “embed”: [“branches”] in the request body. See Example Request below. Please note that this functionality may reduce the endpoint’s performance.
To include a list of Family Items with each item returned in the response, include the query parameter “familyItems”: “true”. See Example Request below. Please note that this functionality may reduce the endpoint’s performance.

Name

Type

Description

filters

array

The list of filter objects for the item search.

filters[].condition

string

The filter condition for the search (e.g., “contains”, “equals”).

filters[].condition = “contains”

filters[].key

enum

The type of filter (e.g., “longDescription”, “itemNumber”).

filters[].values

array

The list of values for the “equals” filter.

filters[].condition = “equals”

filters[].key

enum

The type of filter (e.g., “itemNumber”, “branchNumber”).

filters[].values

array

The list of values for the “equals” or “in” filter.

filters[].joinCondition

string

The filter join condition for the search (e.g., “and”, null).

Pagination

pagination

object

The object containing the pagination details for the search results.

pagination.itemsPerPage

integer

The number of items displayed per page in the search results.

pagination.pageNumber

integer

The current page number being displayed in the search results.

Example Request

Search by Item Number Request Payload

POST /api/product/v1/search/items?familyItems=true HTTP/1.1
Host: partner.abcsupply.com
Authorization: Bearer <TOKEN>
{
  "filters": [
    {
      "key": "itemNumber",
      "condition": "equals",
      "values": [ "02GASTZ3WW"],
      "joinCondition": null
    }
  ],
  "embed": ["branches"],
  "pagination": {
      "itemsPerPage": 20, 
      "pageNumber": 1
    } 
}

Expand

Response

Example Response

Search by Item Number Response Payload

{
    "pagination": {
        "itemsPerPage": 20,
        "pageNumber": 1,
        "totalPages": 1,
        "totalItems": 1
    },
    "items": [
        {
            "itemNumber": "02GASTZ3WW",
            "familyId": "PFam_3346590",
            "familyName": "GAF Timberline High Definition HDZ Architectural Shingles",
            "itemDescription": "GAF StainGuard Timberline High Definition with StrikeZone Shingles Weathered Wood 3 Bdl Per Square",
            "status": "Active",
            "familyItems": [
                {
                    "itemNumber": "02GASTZ3PG",
                    "itemDescription": "GAF StainGuard Timberline High Definition with StrikeZone Shingles Pewter Gray 3 Bundle Per Square",
                    "color": "Pewter Grey"
                },
                {
                    "itemNumber": "02GATZ3CD",
                    "itemDescription": "GAF Timberline High Definition with StrikeZone Shingles Canadian Driftwood 3 Bundle Per Square",
                    "color": "Canadian Driftw"
                }
            ],
            "color": {
                "description": "Product Color",
                "code": "384",
                "name": "Weatherwood"
            },
            "finish": {
                "description": null,
                "code": null,
                "name": null
            },
            "weights": [
                {
                    "value": "0.00010",
                    "uom": null,
                    "description": null
                }
            ],
            "uoms": [
                {
                    "name": "Square",
                    "code": "SQ",
                    "description": "costing"
                },
                {
                    "name": "Bundle",
                    "code": "BD",
                    "description": "stocking"
                }
            ],
            "dimensions": {
                "width": {
                    "value": null,
                    "uom": null,
                    "description": "Width "
                },
                "thickness": {
                    "value": null,
                    "uom": null,
                    "description": "Thickness "
                },
                "height": {}
            },
            "specifications": [
                {
                    "name": "Spec Warranty",
                    "code": "143",
                    "description": "Dimensional Shingles - 143"
                },
                {
                    "name": "Special Attributes",
                    "code": "24",
                    "description": "Standard Colors"
                },
                {
                    "name": "Size Profile",
                    "code": "610",
                    "description": "Metric"
                }
            ],
            "prop65Warnings": [
                {
                    "label": "WARNING: This product can expose you to chemicals including Silica, crystalline (airborne particles of respirable size),Titanium dioxide (airborne, unbound particles of respirable size), which are known to the State of California to cause cancer.  For more information go to www.P65Warnings.ca.gov.",
                    "display": true,
                    "type": "chemical",
                    "locale": "English"
                }
            ],
            "images": [
                {
                    "assetId": "02gastz3ww-product",
                    "type": "PrimaryProductImage",
                    "href": "https://partners.abcsupply.com/product/v1/items/02GASTZ3WW/images/02gastz3ww-product"
                },
                {
                    "assetId": "02gatz3ww-product",
                    "type": "RepresentativeProductImageReference",
                    "href": "https://partners.abcsupply.com/product/v1/items/02GASTZ3WW/images/02gatz3ww-product"
                }
            ],
            "hierarchy": {
                "productGroup": {
                    "name": "1000",
                    "code": "1000",
                    "label": "Steep Slope Products",
                    "description": "Steep Slope Products",
                    "category": {
                        "name": "000013  -  Steep Slope Roofing (<gt/>2:12 Pitch)",
                        "code": "13",
                        "label": "Steep Slope Roofing (<gt/>2:12 Pitch)",
                        "description": "Steep Slope Roofing (<gt/>2:12 Pitch)",
                        "productType": {
                            "name": "000070  -  Fiberglass Laminated Shingles",
                            "code": "70",
                            "label": "Fiberglass Laminated Shingles",
                            "description": "Fiberglass Laminated Shingles",
                            "materialComposition": {
                                "name": "000062  -  Asphalt Composition Shingles and Hip & Ridge",
                                "code": "62",
                                "label": "Asphalt Composition Shingles and Hip & Ridge",
                                "description": "Asphalt Composition Shingles and Hip & Ridge",
                                "warranty": {
                                    "name": "000143  -  Dimensional Shingles",
                                    "code": "143",
                                    "label": "Dimensional Shingles",
                                    "description": "Dimensional Shingles",
                                    "brandLine": {
                                        "name": "GAF Timberline HD  -  003232",
                                        "code": "3232",
                                        "label": "GAF Timberline HD",
                                        "description": "GAF Timberline HD"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "branches": [
                {
                    "number": "32",
                    "links": {
                        "self": "https://api3-sb.abcsupply.com/dev-partners-location/api/location/v1/branches/32"
                    }
                },
                {
                    "number": "668",
                    "links": {
                        "self": "https://api3-sb.abcsupply.com/dev-partners-location/api/location/v1/branches/668"
                    }
                }
            ]
        }
    ]
}

Expand

Name

Type

Description

pagination

object

The object containing pagination information.

pagination.itemsPerPage

integer

The number of items returned per page.

pagination.pageNumber

integer

The current page number of the response.

pagination.totalPages

integer

The number of total pages in the response.

pagination.totalItems

integer

The total number of items returned in the response.

items

array

The array of items available at the user’s branch that meet the search criteria.

items[].itemNumber

string

The ABC Supply item number.

items[].familyId

string

The unique ID for the product family.

items[].familyName

string

The name of the product family.

items[].itemDescription

string

The description of the item.

items[].status

string

The status of the item (e.g., “Active”, “Inactive”).

items[].familyItems

array

The list of items in the product family.

items[].familyItems[].itemNumber

The item number for the item in the product family.

items[].familyItems[].itemDescription

The description of the item in the product family.

items[].familyItems[].color

The color of the item in the product family.

items[].color

object

The object describing the item color.

items[].color.description

object

The description of the color.

items[].color.code

string

The code for the color.

items[].color.name

string

The name of the color.

items[].finish

object

The object describing the item finish.

items[].finish.description

string

The description of the finish. (Available in a future release.)

items[].finish.code

string

The code for the finish, if applicable. (Available in a future release.)

items[].finish.name

string

The name of the finish. (Available in a future release.)

items[].weights

array

The list of available weights of the item.

items[].weights[].value

string

The value of the weight of the item.

items[].weights[].uom

enum

The unit of measure of the weight (e.g., “lbs”).

items[].weights[].description

string

The description of the unit of measure for the weight (e.g., “Weight (lbs.)”).

items[].uoms

array

The list of the units of measure of the item.

items[].uoms[].name

string

The name of the unit of measure.

items[].uoms[].code

string

The code of the unit of measure.

items[].uoms[].description

string

The description of the unit of measure.

items[].dimensions

object

The object describing the product dimensions.

items[].dimensions.width

object

The object describing the product width.

items[].dimensions.width.value

string

The value of the width dimension.

items[].dimensions.width.uom

enum

The unit of measurement of the width dimension.

items[].dimensions.width.description

string

The description of the width unit of measure (e.g., “Width (ft.)”).

items[].dimensions.thickness

object

The object describing the item thickness.

items[].dimensions.thickness.value

string

The value of the thickness dimension.

items[].dimensions.thickness.uom

enum

The unit of measurement of the thickness dimension.

items[].dimensions.thickness.description

string

The description of the thickness unit of measure (e.g., “Thickness (in.)”).

items[].dimensions.height

object

The object describing the height of the item. (Available in a future release.)

items[].specifications

array

The list of specifications for the item.

items[].specifications[].name

string

The name of a specification (e.g., “Spec Warranty”).

items[].specifications[].code

string

The code for the specification.

items[].specifications[].description

string

The description of the specification.

items[].prop65Warnings

array

The list of Proposition 65 warnings for the item.

items[].prop65Warnings[].label

string

The text of the proposition 65 warning.

items[].prop65Warnings[].display

boolean

The Boolean specifying if the warning should be displayed.

items[].prop65Warnings[].type

enum

The type of the Proposition 65 warning (e.g., “chemical”).

items[].prop65Warnings[].locale

string

The localization language of the Proposition 65 warning.

items[].images

array

The list of image links available for the item.

items[].images[].assetId

string

The asset ID of the image link.

items[].images[].type

enum

The type of image link (e.g., “RepresentativeProductImageReference”).

items[].images[].href

string

The URL for the image.

items[].hierarchy

object

The object describing the product hierarchy of the item.

items[].hierarchy.productGroup

object

The object describing the product group of the item.

items[].hierarchy.productGroup.name

string

The name of the product group.

items[].hierarchy.productGroup.code

string

The code for the product group.

items[].hierarchy.productGroup.description

string

The full description of the product group.

items[].hierarchy.productGroup.label

string

The abbreviated description of the product group.

items[].hierarchy.productGroup.category

object

The object describing the product category of the item.

items[].hierarchy.productGroup.category.name

string

The name of the product category.

items[].hierarchy.productGroup.category.code

string

The code for the product category.

items[].hierarchy.productGroup.category.description

string

The full description of the product category.

items[].hierarchy.productGroup.category.label

string

The abbreviated description of the product category.

items[].hierarchy.productGroup.category.productType

object

The object describing the product type of the item.

items[].hierarchy.productGroup.category.productType.name

string

The name of the product type.

items[].hierarchy.productGroup.category.productType.code

string

The code for the product type.

items[].hierarchy.productGroup.category.productType.description

string

The full description of the product type.

items[].hierarchy.productGroup.category.productType.label

string

The abbreviated description of the product type.

items[].hierarchy.productGroup.category.productType.materialComposition

object

The object describing the material composition of the item.

items[].hierarchy.productGroup.category.productType.materialComposition.name

string

The name of the material composition.

items[].hierarchy.productGroup.category.productType.materialComposition.code

string

The code for the material composition.

items[].hierarchy.productGroup.category.productType.materialComposition.description

string

The full description of the material composition.

items[].hierarchy.productGroup.category.productType.materialComposition.label

string

The abbreviated description of the material composition.

items[].hierarchy.productGroup.category.productType.materialComposition.warranty

object

The code for the warranty.

items[].hierarchy.productGroup.category.productType.materialComposition.warranty.name

string

The name of the warranty.

items[].hierarchy.productGroup.category.productType.materialComposition.warranty.code

string

The code representing the warranty.

items[].hierarchy.productGroup.category.productType.materialComposition.warranty.description

string

The full description of the warranty.

items[].hierarchy.productGroup.category.productType.materialComposition.warranty.label

string

The abbreviated description of the warranty.

items[].hierarchy.productGroup.category.productType.materialComposition.brandLine

object

The object describing the brand line of the item.

items[].hierarchy.productGroup.category.productType.materialComposition.brandLine.name

string

The name of the brand line.

items[].hierarchy.productGroup.category.productType.materialComposition.brandLine.code

string

The code for the brand line.

items[].hierarchy.productGroup.category.productType.materialComposition.brandLine.description

string

The full description of the brand line.

items[].hierarchy.productGroup.category.productType.materialComposition.brandLine.label

string

The abbreviated description of the brand line.

items[].branches

array

The list of ABC Supply branches with item availability.

items[].branches[].number

string

The ABC Supply branch number.

items[].items[].branches[].links

object

The object containing reference links for the ABC Supply branch.

items[].branches[].links.self

string

The API reference link for the ABC Supply branch.

HTTP Status Codes

Code

Status

Description

200

The request and response were successfully sent.

400

Bad Request

Confirm the request body and parameters are formatted correctly.

403

Forbidden

The user account does not have access to view data based on provided request parameters.

500

Internal Server Error

The server was unable to process the request.

502

Bad Gateway

The server was unable to complete the request due to upstream errors.

Additional Examples

Example Request

Search by Product Family ID Request Payload

POST /api/product/v1/search/items?familyItems=false HTTP/1.1
Host: partner.abcsupply.com
Authorization: Bearer <TOKEN>
{
  "filters": [
    {
      "key": "productFamilyId",
      "condition": "equals",
      "values": ["PFam_3357501"],
      "joinCondition": null
    }
  ],
    "pagination": {
        "itemsPerPage": 20, 
        "pageNumber": 1
    } 
}

Expand

Example Request

Search by Item Description Request Payload

POST /api/product/v1/search/items?familyItems=false HTTP/1.1
Host: partner.abcsupply.com
Authorization: Bearer <TOKEN>
{
  "filters": [
    {
      "key": "Description",
      "condition": "contains",
      "values": ["Roofing"],
      "joinCondition": null
    }
  ],
    "pagination": {
        "itemsPerPage": 20,
        "pageNumber": 1
    } 
}

Expand