Getting Started

The Promo.zone API is an RPC-style API that uses a JSON-based request and response model.

To make API calls, you simply POST a JSON request that includes information about the supplier whose service that you want to get data from, the ID and password that they've assigned to you, information about the type of API call you want to make (ex: Inventory, Order Status, etc) and any details about the data that you want to retrieve.

For example, suppose that you want to get inventory information for a Starline product. You would send the following payload.

{
  "apiKey": "your-api-key",
  "supplier": "STAR",   
  "id": "your-id",
  "password": "your-password",  
  "service": "INV",
  "version": "1.2.1",  
  "function": "getInventoryLevels",
  "productID": "AF200",
  "productIDType": "Supplier"
}

Let's take a look at the request...

The "apiKey" is a key that you'll use to authenticate with the service. You'll be given an API key when you register for the service.

In this example, we want to get information about a product supplied by Starline. Their supplier code is "STAR," and that's being specified using the "supplier" attribute.

The values of the "id" and "password" attributes are the unique ID and password that were assigned to your company by the supplier.

We're making a call to get inventory information, and this is reflected in the "service" attribute. We're also indicating that we want to use version 1.2.1 of the inventory standard, and this is indicated in the "version" attribute.

Many of the PromoStandards services support multiple functions. For example, version 1.2.1 of the Inventory spec supports two functions: getFilterValues and getInventoryLevels. In this example, the function that we want to use is "getInventoryLevels," and this is reflected in the "function" attribute.

And finally, in this example, we want to get inventory information for Starline product AF200. This is specified using the "productID" value. The value of the "productIDType" attribute ("Supplier") indicates the productID is the supplier's product ID.

The response to the API call will look something like this...

{
  "Status": "200",
  "Response": {
    "Envelope": {
      "Body": {
        "Reply": {
          "productID": "AF200",
          "ProductVariationInventoryArray": {
            "ProductVariationInventory": [
              {
                "partID": "AF200-35-00",
                "partDescription": "Tempo Sports Fitness Belt",
                "quantityAvailable": "1500",
                "attributeColor": "Gray",
                "attributeSize": "NA",
                "entryType": "exact",
                "validTimestamp": "2018-07-13T17:47:26.7337365Z"
              },
              {
                "partID": "AF200-36-00",
                "partDescription": "Tempo Sports Fitness Belt",
                "quantityAvailable": "1050",
                "attributeColor": "Red",
                "attributeSize": "NA",
                "entryType": "exact",
                "validTimestamp": "2018-07-13T17:47:26.749361Z"
              }
              ...
            ]
          }
        }
      }
    }
  }
}			

The value of the "Status" attribute ("200") of the response indicates that the API call was successful. Specifically, it indicates that the API was able to send a request to the supplier's service endpoint, and that it received a response.

The remainder of the response (starting with the "Response" attribute) is a JSON representation of the SOAP response that the supplier returned. To get details about what's in the response, you'd refer to the PromoStandards Inventory spec.


Next Steps

To learn more about the Promo.zone API, explore the API Documentation and FAQ.

If you're interested in testing the API, or if you have any questions, please email Tim Dietrich at timdietrich@me.com.

© Copyright 2019 Dietrich Enterprises, LLC.