Getting Started

Welcome to the Delivery Cloud API getting started guide. You can integrate your product with our API in a coulple of easy steps. Let's begin!

Getting your API key information

  • client_id: This is a unique string used to identify your developer account.
  • client_secret: This is your password to our API. It will be used for authentication. Please treat as confidential.

Using the API

After getting your API information, you can connect to the Delivery Cloud API in two steps.

Getting your token

Before you can call the API method, you need to exchange your API key information for an authentication token. This token would be used in subsequent calls to the API. To get your token, you need to make a POST request to https://api.shoppi.ng/oauth/token The following POST parameters have to be definded in your request:

  • service_id: the value of this should be delivery_cloud
  • client_id: Your API key client ID
  • client_secret: Your API key client secret
  • grant_type: the value of this should be client_credentials
Below is a sample response from the request
{
  "access_token": "eyJhiUUM5OENCSkdQVUIxMDI3UEJZS0VRVE5PWCIsInVzZXJSb2xlcyI6IiIsImNsaWVudFJvbGVzIj",
  "type": "bearer",
  "expires_in": 1209600
}
        

Your token is the value of access_token. This must be included as an Authorization header in all subsequent requests. e.g Authorization: Bearer eyJhiUUM5OENCSkdQVUIxMDI3UEJZS0VRVE5PWCIsInVzZXJSb2xlcyI6IiIsImNsaWVudFJvbGVzIj

Getting Shipment Options

To get shipment options for an order from the Delivery Cloud API, send a GET request in the following format
https://api.shoppi.ng/delivery_cloud/api/v2/shipment_options/town/{town_id}/destination/{destination_town_id}/delivery_service/{delivery_service_id}/category/{category_id}/cost/{cost}/payment_mode/{payment_mode_id}
Here is a sample response
[
  {
    "id": 4164642844350160736,
    "delivery_charge": {
      "base": 80,
      "forwarding": 0,
      "surcharge": 4,
      "total": 84
    },
    "delivery_provider": {
      "id": "2d728c5aa53e4bc99002e1c58e54b346",
      "business_name": "Diji Courier",
      "delivery_policy": "",
      "display_name": "Diji Courier",
      "marketing_info": "The Best",
    }
  }
]
        

Creating A shipment

To create shipment, send a POST request to https://api.shoppi.ng/delivery_cloud/api/v2/shipments. The body of the request should be as follows

{
    "merchant": {
        "id": "9f86a066a04a4a9e908e837cf6614f0e"
    },
    "customer": {
        "customer_id": "cust001",
        "first_name": "Diji",
        "last_name": "Adeyemo",
        "address": {
            "name": "Ikota",
            "town_id": 1241,
            "city": "lagos",
            "state": "lagos",
            "country": "nigeria"
        },
        "phone_number": "08125595656",
        "email": "dijia@shoppi.ng"
    },
    "seller": {
        "name": "Super Seller",
        "address": {
            "name": "Ikota",
            "town_id": 1241,
            "city": "lagos",
            "state": "lagos",
            "country": "nigeria"
        },
        "phone_number": "08125595656",
        "email": "super@seller.com"
    },
    "delivery_provider": {
        "id": "2d728c5aa53e4bc99002e1c58e54b346"
    },
    "cost": 2000.00,
    "delivery_service": {
        "id": 1
    },
    "delivery_category": {
        "id": 1
    },
    "payment_mode": {
        "id": 1
    },
    "verification": "none",
    "shipment_products": [
        {
            "product_id": "cccc123323423",
            "summary": "Red Shirt",
            "description": "Beautfuful Red Shirt",
            "quantity_in_bike": 20,
            "quantity": 3,
            "weight": 30
        }
    ]

}	
  • cost: Decimal is the cost of the item(s) being shipped. This should not inculde the delivery charges.
  • merchant: Object representing the merchant account creating this shipment. This has the following fields
    • id: This is your Shopping 32-character merchant ID assigned to you by Shopp!ng. It is avaiable in the Developer Information section of your Merchant Dashboard
  • customer: This is an object containing information about the customer. It has the following fields
    • customer_id: String representing customer id. This is generated by the developer.
    • first_name: Customer's first name
    • last_name: Customer's last name
    • phone_number: Customer's phone number
    • email: Customer's email address
    • address: An object representing the customer's delivery address. It has the following fields
      • name: This should typically contain the full address
      • city: Delivery address city
      • state: Delivery address state
      • country: Delivery address country
      • town_id: Delivery address town ID
  • seller: This is an object containing information about the seller. It has the following fields
    • id: String representing seller id.
    • name: Seller name
    • phone_number: Seller's phone number
    • email: Seller's email address
    • address: An object representing the selleer's delivery address. It has the following fields
      • name: This should typically contain the full address
      • city: Delivery address city
      • state: Delivery address state
      • country: Delivery address country
      • town_id: Delivery address town ID
  • delivery_provider: Object representing the delivery provider selected by the customer. It has the following fields
    • id: String ID of the delivery provider
  • delivery_service: Object representing the delivery service selected by the customer. It has the following fields
  • payment_mode: Object representing the payment mode selected by the customer. It has the following fields
  • verification: String representing the name of the customer verification method to be used for delivery. If there is no verification method associated with your account or you do not need to verify the customer on delivery, the value here should be "none". See getting verification methods
  • shipment_products:: An array of objects containing each item in the shipment. Each object has the following fields:
    • product_id: Unique ID of the product. Provided by the developer.
    • summary: Summary of the product
    • description: A longer description of the product
    • quantity_in_bike: : Integer represent how many of this product will fit in a bike.
    • quantity: : Integer representing quantity of this item in the shipment
    • weight: : Decimal represent the weight of an individual item in kilograms. This is optional if you provided quantity_in_bike
On successful creation,the input object is returned back along with an id field representing the assigned ID of the shipment
{
    "id": "4235jh35kh"
}
        

Getting Shipment Notifications

When the status of a shipment is updated, a notification is sent to you by making a GET request the callback URL associated with your account along with the following parameters.

For example, If your callback URL is http://example.com/shipment_status the full callback URL for a newly created shipment with ID 1234567890 would be http://example.com/shipment_status?shipment_id=1234567890&shipment_status_id=1

Getting Delivery Services

To get available delivery services, send a GET request to https://api.shoppi.ng/delivery_cloud/api/v2/delivery_services

Getting Delivery Categories

To get available delivery categories, send a GET request to https://api.shoppi.ng/delivery_cloud/api/v2/delivery_categories

Getting Payment Modes

To get available payment modes, send a GET request to https://api.shoppi.ng/delivery_cloud/api/v2/payment_modes

Getting Shipment statuses

To get all available shipment statuses, send a GET request to https://api.shoppi.ng/delivery_cloud/api/v2/shipment_status

Getting Town IDs

To get all available town IDs, send a GET request to https://api.shoppi.ng/delivery_cloud/api/v2/location/towns

Getting available customer verification methods

To get all available verification methods associated with your account, send a GET request to https://api.shoppi.ng/delivery_cloud/api/v2/verifications