API Overview

Getting Started

Welcome to Public API documentation!
Here are some resources that will help you understand the basics of our APIs. If you haven’t already, make sure that you have familiarized yourself with the Terms of Use. Check out the OAuth section and API Authentication to learn more about how we do authentication and authorization.

Back To Top

API Authenication

Every API request should be shipped with app_id and app_secret, app_id is your application identifier that you get once you create your app on your API dashboard, your application identifier once assigned can not be changed. Your app_secret is an auto-generated key that you will be given along with the app_id. app_secret can be changed at any time.

Both app_id and app_secret should be present in your API request in order to be granted access and get valid response in return. If one is missing or is invalid, the API request will be denied and you will get 403 error in return.

Back To Top

OAuth 2.0 API follows OAuth 2.0 RFC, we will give brief you on how the authorization works, but you can alway refer back to the rfc if you want dig further.

Whenever you want to obtain an access token, you need to redirect the user to the following URL:

With the following params:

Param Name Value(s)
redirect_uri  The url/page that we should redirect to after the authorization step
response_type  Web server applications should use “code”
scope  Comma delimited set of permissions
client_id  Your app_id
state (optional)  session management between the client and the server

In response to this request the user will be redirected to login screen hosted by, where the user grant the API client (consumer) the access requested. After successful login the user will be redirected to redirect_uri provided above.


You will get an authorization code back in the Query String, which you will use later to get an access token.

Now once you have the code (authorization code), you do POST request to the following url to get back an access token and customer_id :

Param Name Value(s)
code The authorization code you received on redirect_uri
client_id Your app_id
client_secret Your app_secret
redirect_uri  Same to one has been used in the first step
grant_type For now the grant_type is always: authorization_code

You will get back the following response:

Param Name Value(s)
access_token Access token.
customer_id  Souq customer identifier
refresh_token A token that may be used to obtain a new access token.
expires_in The remaining lifetime of access token in seconds.
token_type For now the token_type is always: Bearer


Back To Top

API Endpoints


/products is the API endpoint that you use to search inventory of products and to retrieve a specific product details. You can use the API console to learn more about this API endpoint, its input parameters and its response.

Back To Top


/offers is the API endpoint that you use to retrieve list of offers available for specific product or retrieve single offer by offer id. You can use the API console to learn more about this API endpoint, its input parameters and response.

Back To Top