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

Ruby

PHP

Javascript

Golang

Response Sample

401

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

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

Ruby

PHP

Javascript

Golang

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

200

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"
}