Grid Products API Reference

This is the API reference for integrating with Grid Products. It provides detailed information on endpoints, authentication, and examples for retrieving, updating, and managing your product data.

Postman Collection

For easy testing and configuration, you can import our ready-to-use Postman collection into Postman.

Configuration Notes:

1. URL Placeholders: Replace <tenant-id>, <environment>, and <space-id> with your actual values.
2. Data Residency: Replace <data-residency> with one of the following: eu, us, in, au, or uae.
3. Headers: Set the x-api-key or Authorization header to your generated access token from the Grid Console.

Authentication

To use the Grid Products API, every request requires an access token. Here's how to generate one:

1. Go to the Apps → Developer tab in the Phygrid Console.
2. Generate an access token.
3. Add the token as an x-api-key in your request headers.

URL Overview

The {base-url} for the Grid Products API varies based on your data residency. Use the correct region-specific URL from the table below:

Replace {tenant-id} with your tenant ID and {environment} with the environment where your products data will live (e.g., dev, staging).

Endpoints Overview

Here's a quick overview of available API endpoints:

Working with Products

Fetch Products

Retrieve products with a GET request:

GET {base-url}/{tenant-id}/{environment}/products
POST {base-url}/{tenant-id}/{environment}/products

Response

{
  list: Array<Partial<GridProduct>>,
  count: number,
  facets:  {  [propertyName]: FacetResults[] },
  attributeFilters: { [key]: string[] }
}

Reference: GridProduct

Query Parameters

Use the following parameters as GET properties in the URL to refine your results:

GET Product by ID

Retrieve a specific product by its ID:

GET {base-url}/{tenant-id}/{environment}/products/{productGroupId}

Response

Returns Partial<GridProduct>

Query Parameters

To use query parameters, add them as GET properties to the URL.

GET Product By Barcode

Retrieves a specific product by barcode ID. Variants checked:

• globalTradeItemNumber
• europeanArticleNumber
• universalProductCode

GET {base-url}/{tenant-id}/{environment}/products-barcode/{barcode}

Response

{
    productDetails: Partial<GridProduct>,
    productId: string
}

Reference: GridProduct

Query Parameters

To use query parameters, add them as GET properties to the URL.

GET Search

Searches products or product types by keyword.

{base-url}/{tenant-id}/{environment}/search

Response

{
  products: Array<Partial<GridProduct>>,
  productTypes: Array<ProductType>
}

Reference: GridProduct, ProductType

Query Parameters

To use query parameters, add them as GET properties to the URL.

GET Product Recommendations by ID

Retrieves a list of product recommendations taken from RelatedProductGroups

GET {base-url}/{tenant-id}/{environment}/product-recommendations/{productGroupId}

Response

Array<Partial<GridProduct>>

Query Parameters

To use query parameters, add them as GET properties to the URL.

POST Push Products

This API allows you to upload or merge products following the GridProduct format. The only required field is productGroupId , while other fields are optional.

Body

The body of the request should be an Array of GridProducts JSON format using the content-type header application/json.

Payload

Please ensure that the productGroupId is always included in the payload.

You have the flexibility to send either a single product field, multiple fields, or the entire product in your payload.

We will provide two payload examples to illustrate both the replace and merge operations:

1. When sending the productName and productDescription in the payload, both of these fields will undergo updates, with the existing values being replaced by the new ones.

     curl --location '{base-url}/{tenant-id}/{environment}/products-push' \
   --header 'Content-Type: application/json' \
   --data '{
    "data": [
            {
                "productGroupId": "<product-group-id>",
                "productName": [
                    {
                        "isoLanguageId": "en-GB",
                        "productName": "<product-name>"
                    },
                    {
                        "isoLanguageId": "en-US",
                        "productName": "<product-name>"
                    }
                ],
                "productDescription": [
                    {
                        "isoLanguageId": "en-GB",
                        "productDescription": "<product-description>"
                    },
                    {
                        "isoLanguageId": "en-US",
                        "productDescription": "<product-description>    "
                    }
                ]
            }
    ]
   }'

2. When including the roductPriceList and productItemQuantity in the payload, these fields will be subject to updates through a merge operation using the productId and spaceId as key parameters.

   curl --location '{base-url}/{tenant-id}/{environment}/products-push' \
   --header 'Content-Type: application/json' \
   --data '{
    "data":[
        {
            "productGroupId": "xxxxxxx",
            "productPriceList": [
                {
                  "isoLanguageId": "en-GB",
                  "productId": "xxxxxxx",
                  "isoCurrencyCode": "EUR",
                  "listPrice": 1140,
                  "priceListType": "Standard",
                  "spaceId": "xxxxxxx"
                },
                {
                  "isoLanguageId": "en-GB",
                  "productId": "xxxxxxx",
                  "isoCurrencyCode": "USD",
                  "listPrice": 11401,
                  "priceListType": "Standard",
                  "spaceId": "xxxxxxx"
                }
            ],
            "productItemQuantity": [
                {
                  "productId": "xxxxxxx",
                  "productItemQuantity": 90,
                  "spaceId": "xxxxxxx"
                },
                {
                  "productId": "xxxxxxx",
                  "productItemQuantity": 910,
                  "spaceId": "xxxxxxx"
                }
            ]
        }
   
    ]
   }'

The spaceIds array is not included in the request payload. Instead, it is automatically populated based on the values of productPriceList, productStatus, and productItemQuantity.

Limitations: 100 products per batch

DELETE Space Products

This API detaches products from space by sending an array of productGroupId. It will remove these products from the specified space and any relevant subfields in the GridProduct that are related to this space.

Body

Response

Upon a successful request, the API will return a JSON response with status information for each product removed.

{
    "data": [
        {
            "productGroupId": "045xxx",
            "status": 202
        },
        {
            "productGroupId": "046xxx",
            "status": 202
        },
        ....
    ]
}

DELETE Products

Removes products from the Grid Products database based on specified ID's

DELETE {base-url}/{tenant-id}/{environment}/products

PATCH (Update) Products

Updates products with the fields specified in the data object. Shallow-update is performed. Fields not passed in this call will remain the same. Fields containing Arrays or Objects will be completely overwritten.

PATCH {base-url}/{tenant-id}/{environment}/products

Limitations: 100 records per batch

GET Product Variant

Retrieves a specific variant by ID

GET {base-url}/{tenant-id}/{environment}/variants/{productId}

Response

Returns [VariantInfo](data-model)

Query Parameters

PATCH (Update) Variants

Updates variants with the fields specified in the data object without requiring the product's productGroupId. Shallow-update is performed. Fields not passed in this call stay the same. Fields containing Arrays or Objects (productPriceList and productItemQuantity) with the matching specified variant's productId and spaceId only will be upserted.

PATCH {base-url}/{tenant-id}/{environment}/variants

Query Parameters

Reference: [VariantUpdateFields](data-model)

Product Types

GET Product Types List

Returns list of product types associated with the tenant id and environment

GET {base-url}/{tenant-id}/{environment}/product-types

Response

Returns Array<ProductType>

Query Parameters

GET Product Type Details

Returns details of a specific product type

GET {base-url}/{tenant-id}/{environment}/product-types/{productTypeId}

Response

Returns [ProductType](data-model)

Query Parameters

POST Product Types

Update or insert product types to database

Response

Returns Array<[OperationResponse](https://docs.microsoft.com/en-us/javascript/api/@azure/cosmos/operationresponse?view=azure-node-latest)>

Limitations: 100 product types documents per batch

Reference: ProductType

DELETE Product Types

Removes product types from the Grid Products database based on specified ids

DELETE {base-url}/{tenant-id}/{environment}/product-types

Response

Returns Array<{ id: string; status: number; }>

Query Parameters

Reference: ProductType