Documentation

Ingrid Shipping CLI

Overview

Welcome to the comprehensive guide for Ingrid Shipping CLI! This powerful product allows merchants to showcase their delivery options directly on Google Shopping and other marketing platforms. By utilizing advanced algorithms, Ingrid Shipping CLI strives to calculate and present the most cost-effective delivery price for each product, ultimately enhancing the customer experience and driving sales.

Download and install the Ingrid Shipping CLI

To download and install the Ingrid Shipping CLI, follow these steps:

  1. Download the desired tar.gz from https://storage.googleapis.com/ingrid-shipping/{key}, where the {key} is the desired version. Available versions can be found under Contents.Key at https://storage.googleapis.com/ingrid-shipping. Instruction how to download the data programmatically can be found here. The name of the bucket is ingrid-shipping.
  2. Unpack the tar.gz file
  3. Run the ingrid-shipping file

Running Ingrid Shipping CLI commands

It is possible to run the binary in two modes:

Required Ingrid Shipping CLI arguments

We require two arguments to run the Ingrid Shipping CLI:

./ingrid-shipping -site-id=<YOUR_SITE_ID> -site-key=<YOUR_PRIVATE_KEY>

Site id and site key are different per environment and can be found in the Merchant Admin Dashboard:

To copy site id and site key from MAD platform:

  1. Go to https://mad-stage.ingrid.com/ or https://mad.ingrid.com/
  2. Log in to MAD platform
  3. In the header click on the i icon
  4. Click on the Checkout tab
  5. Copy the Site ID and Private key (base64) values

By default, the CLI will connect to the stage environment. To connect to the prod environment use the -env option:

./ingrid-shipping -env="prod"

Start Ingrid Shipping CLI HTTP server

To start the HTTP server run ingrid-shipping command with the -serve option:

./ingrid-shipping -serve

The HTTP server will start on the default port 6061. To change the port use the -addr option:

./ingrid-shipping -serve -addr="0.0.0.0:9090"

Run Ingrid Shipping CLI cli mode

In the batch mode you can pass multiple products in JSON format to the CLI. The CLI will calculate the price for each product and return the result.

> cat '[{"total_value": 1000, "item": {"quantity": 1, "price": 1000}, "country": "SE"}]' | ./ingrid-shipping -site-id=<YOUR_SITE_ID> -site-key=<YOUR_PRIVATE_KEY>
{ "prices": [1000] }

Command line arguments

Variable Description Required in CLI mode Required in HTTP server mode Default value Example value
site-id site ID Y Y n/a -site-id="f05cb447-2c51-448c-bae7-c40f03adad47"
site-key Bearer token, base64 encoded Y Y n/a -site-key="asd123="
env From which Ingrid's env should the site config be fetched N N stage -env="prod"
serve Specifies if the HTTP mode should be used N Y false -serve=true
addr HTTP server address N N :6061 -addr=":9090"
site-ttl TTL for a site config in HTTP mode. Units are in minutes N N 1 minute -site-ttl="1h"
ignored-category-ids Comma separated category ids to ignore N N n/a -ignored-category-ids="hemleverans-45cea3689a844eaf941554126b923266"
ignored-delivery-types Comma separated delivery types to ignore N N n/a -ignored-delivery-types="INSTORE,PICKUP"
version Prints the version of the CLI N N false -version

Calling the HTTP server api

Ingrid Shipping CLI in HTTP server mode contains APIs to:

Get the lowest price for a single product

To get the lowest price for a single product send a POST request to the /price/calculate endpoint:

curl http://localhost:6061/price/calculate --header "Content-Type: application/json" -d '{
	"cart": {
		"total_value": 1000,
		"item": {
			"quantity": 1,
			"price": 1000
		},
		"country": "SE"
	}
}'

In case of success the response will contain the price:

{ "price": 1000 }

In case of error the response will contain an error message:

{ "message": "no delivery options available for given cart and country (misconfiguration)" }

Get multiple products lowest prices

To get the lowest prices for multiple products send POST request to /price/calculate.batch endpoint:

curl http://localhost:6061/price/calculate.batch --header "Content-Type: application/json" -d '{
	"carts": [
	    {"total_value": 1000,"item": {"quantity": 1,"price": 1000},"country": "SE"},
	    {"total_value": 2000,"item": {"quantity": 1,"price": 2000},"country": "NO"}
    ]
}'

The response will contain both prices and errors, if there are any, for each product:

{
    "prices": [1000, -1],
    "errors": [
        {"message":"item 2: no delivery options available for given cart and country (misconfiguration)"}
    ]
}

If cart has no delivery options available, the price will be -1.

Debug the lowest price for a single product

This API is helpful for understanding why the price is calculated in a certain way. It returns all the delivery options for the given cart and country that are valid.

Send exactly the same request to /price/calculate.debug endpoint as for /price/calculate:

curl http://localhost:6061/price/calculate.debug --header "Content-Type: application/json" -d '{
	"cart": {
		"total_value": 1000,
		"item": {
			"quantity": 1,
			"price": 1000
		},
		"country": "SE"
	}
}'

The response contains more data:

{
  "price": 1000,
  "options": [
    {
      "price": 1000,
      "shipping_method": "isb-express",
      "region_id": "sweden-region-id",
      "category_id": "ombudsleverans-category-id",
      "category_name": "Ombudsleverans",
      "delivery_type": "pickup"
    }
  ]
}

Healthcheck

To check the health of the server send a GET request to the /health endpoint:

curl http://localhost:6061/health

The response will contain 200 status and empty body.

Performance

Our benchmarks show that Ingrid Shipping CLI is highly performant:

Results calculated on: MacBook Pro 14-inch 2023, Chip Apple M2 Pro, Memory 32 GB.

Last updated: Fri, Dec 20, 06:15 AM