Promotions & Discount

See available sales discounts and rates promotions.

The Promotions feature allows users to apply discounts to shipment rates. The SHiiP sales team can create unique promo codes tailored to specific shipment types, date ranges, weight limits, or geographical restrictions (such as countries and states).

To determine if any discounts are available for your customers or to apply them via an endpoint before booking a shipment, follow these three steps:

1. Retrieve Promotions: Use the get-all-promotions endpoint to fetch all available promo codes.

2. Apply a Promo Code: Select the desired discount code and call the apply endpoint to activate it for your shipment.

3. Attach Discount Payload: Include a sample discount payload in the bookShipment endpoint request to ensure the discount is successfully applied on our end.

Get All Promotions

This is used to get all available promotions that could be used.

Request Sample

Curl

curl --location 'https://delivery-staging.apiideraos.com/api/v2/token/promotions' \
--header 'Authorization: Bearer Secret Key'

Python

import requests

url = "https://delivery-staging.apiideraos.com/api/v2/token/promotions"

payload = {}
headers = {
  'Authorization': 'Bearer Secret Key'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Ruby

require "uri"
require "net/http"

url = URI("https://delivery-staging.apiideraos.com/api/v2/token/promotions")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer Secret Key"

response = https.request(request)
puts response.read_body

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://delivery-staging.apiideraos.com/api/v2/token/promotions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer Secret Key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Javascript

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer Secret Key");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow"
};

fetch("https://delivery-staging.apiideraos.com/api/v2/token/promotions", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Golang

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://delivery-staging.apiideraos.com/api/v2/token/promotions"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer Secret Key")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Response Sample

401

{
    "status": false,
    "message": "Secret Key not found",
    "status_code": 401
}

200

{
    "data": [
        {
            "code": "CASTWINTER",
            "description": "Use this code for 10% discount for all local shipments from 5th November to 15th November 2024."
        }
    ],
    "message": "Promotions retrieved",
    "status_code": 200
}

Apply Discount

Select a promotion code and apply a discount.

Payload Validation

Field	Type	Required	Validation Rules	Description
code	String	Yes	Must be a valid string, gotten from the all promotion response	A unique code representing a promotion
amount	Integer	Yes	Must be a positive integer.	The shipment rate selected
fromCountryCode	String	Yes	Must be a valid string and a valid country_code	Country the shipment originates from
toCountryCode	String	Yes	Must be a valid string and a valid country_code	Country the shipment is being sent to
shipmentType	String	Yes	Must be a string	Type of shipment, e.g., interstate, international.
weight	String	Yes	Must be a string	Weight of the shipment, typically in kilograms.
courier	String	Yes	Must be a string	The courier service handling the shipment.

Request Sample

Curl

curl --location 'https://delivery-staging.apiideraos.com/api/v2/token/promotions/apply' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Secret Key' \
--data '{
    "code": "JAY10",
    "shipmentType": "interstate",
    "amount": 10000,
    "fromCountryCode" : "NG",
    "toCountryCode" : "NG",
    "weight": "15",
    "courier": "uber"
}'

Python

import requests
import json

url = "https://delivery-staging.apiideraos.com/api/v2/token/promotions/apply"

payload = json.dumps({
  "code": "JAY10",
  "shipmentType": "interstate",
  "amount": 10000,
  "fromCountryCode": "NG",
  "toCountryCode": "NG",
  "weight": "15",
  "courier": "uber"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer Secret Key'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Ruby

require "uri"
require "json"
require "net/http"

url = URI("https://delivery-staging.apiideraos.com/api/v2/token/promotions/apply")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer Secret Key"
request.body = JSON.dump({
  "code": "JAY10",
  "shipmentType": "interstate",
  "amount": 10000,
  "fromCountryCode": "NG",
  "toCountryCode": "NG",
  "weight": "15",
  "courier": "uber"
})

response = https.request(request)
puts response.read_body

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://delivery-staging.apiideraos.com/api/v2/token/promotions/apply',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "code": "JAY10",
    "shipmentType": "interstate",
    "amount": 10000,
    "fromCountryCode" : "NG",
    "toCountryCode" : "NG",
    "weight": "15",
    "courier": "uber"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer Secret Key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Javascript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer Secret Key");

const raw = JSON.stringify({
  "code": "JAY10",
  "shipmentType": "interstate",
  "amount": 10000,
  "fromCountryCode": "NG",
  "toCountryCode": "NG",
  "weight": "15",
  "courier": "uber"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://delivery-staging.apiideraos.com/api/v2/token/promotions/apply", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Golang

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://delivery-staging.apiideraos.com/api/v2/token/promotions/apply"
  method := "POST"

  payload := strings.NewReader(`{
    "code": "JAY10",
    "shipmentType": "interstate",
    "amount": 10000,
    "fromCountryCode" : "NG",
    "toCountryCode" : "NG",
    "weight": "15",
    "courier": "uber"
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer Secret Key")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Response Sample

422

{
    "status": false,
    "message": "The code field is required., The amount field is required., The from country code field is required., The to country code field is required., The shipment type field is required., The weight field is required., The courier field is required."
}

403

{
    "message": "Promotion is expired",
    "status_code": 403
}

200

{
    "message": "Promotion is applied successfully",
    "status_code": 200,
    "data": {
        "total_amount": 10000,
        "discounted_amount": 8500,
        "promotion_code": "JAY10",
        "promotion_name": "Special promotion for festive customers!",
        "promotion_criteria": "shipment_type",
        "percentage_off": 15
    }
}

Attach Payload

After successfully applying the discount code, use the payload below when calling the bookShipment endpoint. This ensures the discount is properly applied when the shipment is processed by our system.

{
  "discount": true,
  "discount_code": "JAY10"
}