Halla I/O (2.0.0)

Download OpenAPI specification:Download

Getting Started:

  1. Obtain Credentials (Please Contact Halla to Obtain Credentials):

    1. 'serviceAccount': Add your Service Account in the header for all API requests to the Halla services. This is used to track API usage for authorization, billing, etc.

    2. 'key': Add your API Key to the query for all API requests to the Halla services. This is used as a first line of defense to authenticate API requests.

  2. Add Your Catalog:

    1. Use the POST STORE route to create a virtual product catalog. Please add a minimum of 1 thousand products per store, each with a 'primaryId' and 'label'. This will trigger Halla to index the catalog, allowing for Recommendation, Substitution, and Search services within minutes.

  3. Get Recommendations:

    1. Use the GET PRODUCTS route and set the strategy to 'recommend'.

    2. Fill in the 'storeId' query parameter to use a specific catalog.

    3. Provide one or more of the following query parameters:

      1. 'productId': Biases recommendations to be relevant for a specific product.

      2. 'cartProductIds': Biases recommendations to be relevant for all products in the cart.

      3. 'consumerId': Biases recommendations to be relevant for the consumer's previous browsing and past purchase history.

    4. If multiple inputs are given, the recommendations will be blended to best satisfy multiple constraints.

  4. Get Substitutions:

    1. Use the GET PRODUCTS route and set the strategy to 'substitute'.

    2. Fill in the 'storeId' query parameter to use a specific catalog.

    3. Fill in the 'productId' query parameter.

  5. Get Search Results:

    1. Use the GET PRODUCTS route and set the strategy to 'search'.

    2. Fill in the 'storeId' query parameter to use a specific catalog.

    3. Fill in the 'text' query parameter.

  6. Supercharge Performance with Purchases:

    1. Use the POST ORDER route to add one or more transactions to our system. Transactions will be used to fine tune our models to provide a better experience for your shoppers. To enable advanced personalization, please provide the 'consumerId' field.

Advanced Integration:

  • Integrate Multi-Tenant Capabilities:

    • Ensure that store and product ids are globally unique across all tenants. If needed, tenant name can be appended to the id in question to guarantee uniqueness.

    • Attach 'brand' field to allow for better personalization at scale.

  • Enable Real-Time Inventory:

    • Integrate the POST STORE route into your inventory management solution and do one of the following:

      • Call the POST STORE route at regular intervals to overwrite existing store data.

      • Call the ADD / DELETE product from store routes to update the catalog upon changes and current availabilities.

  • (BETA) Enable Advanced Filtering:

    • To enable SNAP, Own-Brand, Sponsored Product and other custom filters, create multiple virtual stores for each real store location. Each virtual store should correspond to a subset of products to include in the filter. Store ids can be generated by prepending the filter identifier to your store id.

  • (BETA) Run an A/B Test:

    • Work with your Halla Support Rep to define the scope of your A/B test.

    • Call the POST ORDER route to add purchases with which to evaluate.

    • If you are tracking spend between test groups, then it is required to attach the 'campaign' field in the request body of the order.

    • If you are testing at the consumer level, then it is required to attach the 'consumerId' field in the request body of the order.

  • (BETA) Add Fulfillment Data:

    • Call the POST ORDER route multiple times corresponding to when an order is placed and later fulfilled. Set the 'code' attribute in each item to 'purchased' or 'fulfilled' corresponding to the order status.

Authentication

api_key

Security Scheme Type API Key
Query parameter name: key

Get Products

Real-time, contextual product recommendation, substitution and search. Returns a list of products with attached relevance scores.

Authorizations:
query Parameters
strategy
required
string
Enum: "recommend" "substitute" "search"

Determines which service should be used for this request.

filters
string
Enum: "PREVIOUSLY_PURCHASED" "NEVER_PURCHASED"

Optional filter to further restrict the domain of response products beyond the storeId. PREVIOUSLY_PURCHASED will restrict the domain to just products that a consumer has previously purchased, if consumerId is invalid no products will be returned. NEVER_PURCHASED will restrict the domain to just products that a consumer has not previously purchased, if consumerId is invalid this filter will not be applied. Note that products contained in productId and cartProductIds request fields are removed by default.

text
string

Text input if search strategy is selected.

productId
string

Subscriber specific product identifier to recommend based on. Required for substitution strategy.

cartProductIds
string

A comma delimited string of subscriber specific product identifiers for a consumer's current cart. If productId is not passed in the query, then recommendations will be based on the cartProductIds. If a productId is passed in the query, then cartProductIds will be used to improve recommendation relevance.

consumerId
string

Subscriber specific consumer identifier to personalize recommendations. If productId and cartProductIds are not passed in the query, then recommendations will be based on previous consumer behavior.

storeId
string

Subscriber specific store identifier, selecting the catalog of products to recommend from. If storeId is invalid or is not passed in the query, then recommendations will be sourced from the subscriber's master product list.

limit
integer

Upper bound on the number of products to return. Default = 15. Max = 30.

header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Add Orders

Adds new orders, updating associated consumer profiles to allow for real-time personalization.

Authorizations:
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Request Body schema: application/json

The orders to create.

Array of objects (Order)

Responses

Request samples

Content type
application/json
{
  • "orders":
    [
    ]
}

Add Store

Creates / overwrites a store with a distinct catalog. Notes: -Halla will perform best on inventories between 1,000 and 50,000 products. -Primary product ids persist across multiple stores for a given client.

Authorizations:
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Request Body schema: application/json

The store to create.

id
required
string

Used across services to link to this store object.

channel
string
Enum: "E_COMMERCE" "SELF_SCAN" "SMART_CART" "PROMOTIONS" "OTHER"

The application type that will be using Halla's services.

type
string
Enum: "GROCERY_STORE" "SUPER_STORE" "CONVENIENCE" "DELI" "OTHER"

The type of store that will be using Halla's services.

brand
string

Brand of store.

postalCode
string

postal code of store location.

country
string

2 digit country abbreviation. 'US for United States and UK for United Kingdom.'

Array of objects (Product)

Products in the given store's catalog.

object (ProductSummary)

Descriptive information on a store's products.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "channel": "E_COMMERCE",
  • "type": "GROCERY_STORE",
  • "brand": "string",
  • "postalCode": "string",
  • "country": "string",
  • "products":
    [
    ],
  • "productSummary":
    {
    }
}

Get Store Ids

Gets all store ids.

Authorizations:
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Add Products To Many Stores

Bulk method to apply product updates across multiple stores. Note: OVERWRITE will remove products with matching product ids in stores not provided in the request.

Authorizations:
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Request Body schema: application/json

The updates to apply.

Array of objects (ProductUpdate)

Responses

Request samples

Content type
application/json
{
  • "updates":
    [
    ]
}

Delete Store

Deletes store data.

Authorizations:
path Parameters
sid
required
string

Subscriber specific store id

header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Get Store

Gets store data.

Authorizations:
path Parameters
sid
required
string

Subscriber specific store id

header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Add Products To Store

Adds one or more products to a store. This method will create a new store if the store id does not exist and will index the newly created products, letting these products be used as input to the Halla services. \nNotes: \n-Halla will perform best on inventories between 1,000 and 50,000 products. \n-Primary product ids persist across multiple stores for a given client. \n-Never before seen products will be added in minutes.

Authorizations:
path Parameters
sid
required
string

Subscriber specific store id

header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Request Body schema: application/json

The products to create.

Array of objects (Product)

Responses