# Promotions & Discount

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`](#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`](/api-references/book-shipment.md) 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

{% tabs %}
{% tab title="Curl" %}

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

{% endtab %}

{% tab title="Python" %}

```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)

```

{% endtab %}

{% tab title="Ruby" %}

```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

```

{% endtab %}

{% tab title="PHP" %}

```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;

```

{% endtab %}

{% tab title="Javascript" %}

```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));
```

{% endtab %}

{% tab title="Golang" %}

```go
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))
}
```

{% endtab %}
{% endtabs %}

### Response Sample

{% tabs %}
{% tab title="401" %}

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

{% endtab %}

{% tab title="200" %}

```json
{
    "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
}
```

{% endtab %}
{% endtabs %}

## Apply Discount

Select a promotion code and apply a discount.

### Payload Validation

<table data-header-hidden><thead><tr><th width="181"></th><th width="99"></th><th width="109"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Validation Rules</strong></td><td><strong>Description</strong></td></tr><tr><td><code>code</code></td><td>String</td><td>Yes</td><td>Must be a valid string, gotten from the all <a href="#get-all-promotions">promotion</a> response </td><td>A unique code representing a promotion</td></tr><tr><td><code>amount</code></td><td>Integer</td><td>Yes</td><td>Must be a positive integer.</td><td>The shipment rate selected</td></tr><tr><td><code>fromCountryCode</code></td><td>String</td><td>Yes</td><td>Must be a valid string and a valid country_code</td><td>Country the shipment originates from</td></tr><tr><td><code>toCountryCode</code></td><td>String</td><td>Yes</td><td>Must be a valid string and a valid country_code</td><td>Country the shipment is being sent to</td></tr><tr><td><code>shipmentType</code></td><td>String</td><td>Yes</td><td>Must be a string</td><td>Type of shipment, e.g., <code>interstate</code>, <code>international</code>.</td></tr><tr><td><code>weight</code></td><td>String</td><td>Yes</td><td>Must be a string</td><td>Weight of the shipment, typically in kilograms.</td></tr><tr><td><code>courier</code></td><td>String</td><td>Yes</td><td>Must be a string</td><td>The courier service handling the shipment.</td></tr></tbody></table>

### Request Sample

{% tabs %}
{% tab title="Curl" %}

```javascript
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"
}'
```

{% endtab %}

{% tab title="Python" %}

```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)

```

{% endtab %}

{% tab title="Ruby" %}

```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

```

{% endtab %}

{% tab title="PHP" %}

```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;

```

{% endtab %}

{% tab title="Javascript" %}

```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));
```

{% endtab %}

{% tab title="Golang" %}

```go
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))
}
```

{% endtab %}
{% endtabs %}

### Response Sample

{% tabs %}
{% tab title="422" %}

```json
{
    "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."
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}

{% tab title="200" %}

```json
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

## Attach Payload

After successfully applying the discount code, use the payload below when calling the [`bookShipment`](/api-references/book-shipment.md) endpoint. This ensures the discount is properly applied when the shipment is processed by our system.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.goshiip.com/extras/promotions-and-discount.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.