Contents

Overview

Use the UrbanBuz API to connect the different customer data points (profile, sales, loyalty, vouchers, communication and feedback) to the UrbanBuz Customer Data Platform (CDP).

Before you Start

All API calls need to be made using the HTTP protocol to ensure data security. The UrbanBuz APIs are based on Representational State Transfer (REST) standards.
This document is based on REST API version 3. The APIs use (JavaScript Object Notation) JSON as the default message format. You need to use standard HTTP methods to access the UrbanBuz APIs. For example, HTTP GET is used by a client application to retrieve a resource, get data from a Web server or to execute a query.

Common HTTP methods for REST are:

  • GET – Retrieve a resource from the server
  • POST – Update a resource on the server
  • PUT – Create a resource state on the server.
  • DELETE – Remove a resource state on the server.

Note: The credentials will be provided by the UrbanBuz team upon subscription to the platform.

Authentication

UrbanBuz uses customized OAuth 1.0b authentication specification with HMAC-SHA1 signature method that requires a Key and Secret. The following sections explain how to generate an OAuth 1.0b HMAC-SHA1 signature for an HTTP request. This signature is required for passing all UrbanBuz APIs as part of an authorized request. UrbanBuz will provide the Key and Secret along with an OAuth connection library that is required to a create a signature for accessing resources via OAuth (currently using PHP).

Collecting the request method and URL

To create a signature, you need to determine the HTTP method and URL of the request. The base URL is the URL to which the request is directed, excluding any query string or hash parameters. Make sure that the “http//” portion of the URL matches the actual request sent to the API.

Base URL:

http://[subdomain].urbanbuz.com

Query Parameter:

All the query parameter values MUST be URL encoded with UTF-8. See the following example:

http://[subdomain].urbanbuz.com/program/account/search?first=MiKe+Kate

Here, the query parameter value Mike+Kate is encoded to result to MiKe%2BKate.

Collecting the parameters

Collect all the parameters included in the request. There are two locations for these additional parameters - the URL (as part of the querystring) and the request body. In addition to the request parameters, authentication parameters such as auth_key, oauth_nonce, oauth_signature_method, and oauth_timestamp should be included. The parameters (request parameter and authentication parameters) are listed as follows: The values need to be encoded into a single string, called the parameter string.

Parameter Value Description
append_payment True This is the request parameter
oauth_key String API key assigned for the branch or program. Example: pIddeizKeygxPDRuaLNt
oauth_nonce String Random alphanumeric string, uniquely generated to allow the server to verify that a request has never been made before. The nonce value is unique across all requests. Example: lxucb66OAp0
oauth_signature_method String Keyed-hash message authentication specification known as HMAC-SHA1 to sign API calls.
oauth_timestamp String Indicates when the request was created.
branch_code String For a program level authentication, it is required to send the store (branch) code as a header parameter named 'branch_code' to identify the branch from where the request is originating.

The following string will be produced with the parameters collected in the table above:

append_payment=true&oauth_key=xvz1evFS4wEEPTGEFPHBog&oauth_nonce=kYjzVBB8Y0ZFab&oauth_signature_method=HMAC-SHA1&oauth_timestamp=123456789

Creating the signature base string

The three request elements such as HTTP method, base URL, and the parameters must be concatenated to make a single string, from which the signature will be generated. This is called the signature base string by the OAuth specification.

  • HTTP method: The HTTP request method
  • Base URL: The URL the request is being sent to. This URL should not include any query parameters
  • Parameter string: String of the parameters in the request (excluding the oauth_signature parameter). Example: append_payment=true,oauth_key=key&oauth_nonce=nonce&oauth_timestamp=123456789

To encode the HTTP method, base URL, and parameter string into a single string:

  1. Convert the HTTP Method to uppercase and set the output string equal to this value.
  2. Append the ‘&’ character to the output string.
  3. Percent encode the URL and append it to the output string.
  4. Append the ‘&’ character to the output string.
  5. Percent encode the parameter string and append it to the output string.


This will produce the following signature base string:

PUT&http%3A%2F%2Fapi.urbanbuz.com%2Ftxn%2Ftransactions%2Fsubmit&append_payment%3Dtrue%

26oauth_key%3Dtest_key%26oauth_nonce%3D8LbvcvYFqqG5RKl1zhr5%26oauth_timestamp%3D123456789

Generating the signature

The signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The generated signature is then added to the request as oauth_signature before sending it to the API.

API Calls

The following sections describe the different API calls of UrbanBuz.

Account (Customer)

Create account

When a customer transacts for the first time, the Create account API call is invoked to create an account for the customer and a unique customer ID is generated for this customer. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Parameter Type Required Description
first String Not mandatory First name of the customer
last String Not mandatory Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
gender String Not mandatory Gender of the customer
birthdate Date Not mandatory Date of birth of the customer
nationality String Not mandatory Nationality of the customer

Error messages

Error Code Error Message
1004 The following field is not unique
1010 At least one of the following fields is required 
EXAMPLE REQUEST:

 POST http://[subdomain].urbanbuz.com/program/accounts
{
	"profile": {
		"phone": "971520000000",
		"email": "john@email.com",
		"first": "John",
		"last": "Samuel",
		"birthdate": "1988-06-06",
		"gender": "M",
		"city": null,
		"country": null,
		"nationality": "India",
		"language": null,
		"businessFields": {
			"maritalStatus": "Married",	
			"residency": "tourist",	
			"ethnicity": "Asian"
		}
	}
}


EXAMPLE RESPONSE:

{
    "status" : "success",
    "account" : {
         "accountId" : "f64f2940-fae4-11e7-8c5f-ef379131"
    }
}

Search for account

This call is executed to search for the customers associated with a program. The customer list is obtained based on the set search criteria.

Request elements

Parameter Type Required Description
first String No First name of the customer
last String No Last name of the customer
phone String No Phone number of the customer
email String No Email ID of the customer
employeeId String No Employee ID of the customer
businessFieldsRequired String Yes Value required in the response
page Integer Yes Search page number
size Integer Yes Number of records to return by page

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts/search?
   first=Jenn&last=C&businessFieldsRequired=title,street1&page=1&size=10


EXAMPLE RESPONSE:

{
  "pageNumber": 1,
  "pageSize": 10,
  "totalCount": 7,
  "data": [
    {
      "phone": "971502188801",
      "email": "jane@gmail.com",
      "accountId": "2a5676fe-0151-435f-b392-131ab2eae0c5",
      "first": "Jennifer",
      "last": "Christi",
      "birthdate": "1987-09-11",
      "profileSet": "2018-03-26 12:44:55 GST",
      "businessFields": {
        "title": "Mr."
    },    
    {
      "phone": "971502188844",
      "email": "jen124@gmail.com",
      "accountId": "e4670b54-4d13-40c3-a49a-64d225231152",
      "first": "Jennie",
      "last": "Cooks",
      "birthdate": "1987-09-11",
      "profileSet": "2018-03-28 06:56:03 GST",
      "businessFields": {
        "street1": "M street"
      }
    }
  ]
}

Get account by ID

This call is executed to obtain the details of customers (which includes details about their loyalty benefits) by their customer IDs. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
loyalty Boolean Yes Flag to indicate to return loyalty information

Error messages

Error Code Error Message
1005 Data Not Found 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts?
    accountId=f64f2940&phone=971520000000&loyalty=true


EXAMPLE RESPONSE:

{
  "profile": {
   "phone": 971520000000,
   "email": "john@email.com",
   "accountId": "f64f2940",
   "first": "John",
   "last": "Samuel",
   "birthdate": "1988-06-06",
   "gender": "M",
   "city": null,
   "country": null,
   "nationality": "India",
   "language": null,
   "businessFields": {
    "title": "Mr.",
    "maritalStatus": "Married",
    "ethnicity": "Asian"
		}
	},
     "loyalty" : {
       "program" : {
         "name"   : "Loyalty Program Name",
          "logo"   : "URL path to image.jpg"
        },
        "tier" : {
          "name"   : "Loyalty tier name",
          "logo"   : "URL path to image.jpg",
          "order"  : 3,
          "expiry" : "2019-09-09 00:00:00",
          "benefits": "Provide the description of the benefits provided"
        },
        "wallets" : [{
           "countryIso" : "AE",
           "countryName": null,
           "currency"   : "AED",
           "point"      : 1575,
           "value"      : 15.75
        }],
       "redeemable": [
        {
         "countryIso": "AE",
         "countryName": null,
         "currency": "AED",
         "point": 1000,
          "value": 10,
                }
         ],
        "expiry": {
        "point": 256,
        "date": "2018-07-03"
    },
       "toNextTier": 200,
       "cumulativeCredit": 12366.27,
       "balanceDetails": [
     {
        "loyaltyPointsGained": 2345,
        "loyaltyPointsRedeemed": 0,
        "loyaltyPointsExpired": 0,
        "expires": "2018-12-31 00:00:00UTC"
      },
      {
        "loyaltyPointsGained": 142,
        "loyaltyPointsRedeemed": 0,
        "loyaltyPointsExpired": 0,
        "expires": "2020-10-15 00:00:00 UTC"
      }
      ]
}

Update account by ID

This call is executed to update the profile of customers by their IDs. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
first String No First name of the customer
last String No Last name of the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
gender String No Gender of the customer
birthdate Date No Date of birth of the customer
nationality String No Nationality of the customer

Error messages

Error Code Error Message
1004 The following field is not unique
1010 At least one of the following fields required 
EXAMPLE REQUEST:
PUT http://[subdomain].urbanbuz.com/program/accounts?
accountId=f64f2940-fae4-11e7-8c5f-ef379131
{
	"profile": {
		"phone": "971520000000",
		"email": "john@email.com",
		"first": "John",
		"last": "Samuel",
		"birthdate": "1988-06-06",
		"gender": "M",
		"city": null,
		"country": null,
		"nationality": "India",
		"language": null,
		"businessFields": {
                 "title": "Mr.",
         	  "maritalStatus": "Married",
		    "ethnicity": "Asian"
		}
	}
}

EXAMPLE RESPONSE:


 {
    "status" : "success"
}

Get account mapping

This call is executed to obtain all the brands that the account is associated with.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as the query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/​{token}/brand_mappings 

EXAMPLE RESPONSE:

{
     ​"countryIso"  ​: ​"AE"​, 
     ​"countryName"​ : ​"United Arab Emirates"​,   
  ​   "brandId"​     : ​22​,    
     ​"brandName"​   : ​"Bershka" 
}, 
{    
     ​"countryIso"  ​: ​"AE"​,  
   ​  "countryName" ​: ​"United Arab Emirates"​,  
     ​"brandId"     ​: ​45​,    
     ​"brandName"   ​: ​"Zara" }

}
}

Get account communication preferences

This call is executed to obtain the details about the communication preference (opt-out) set by the account.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/
    ​{token}/communication/preferences 

EXAMPLE RESPONSE:

 {    
    ​"channel"     ​: ​1​, 
    ​"channelName" ​: ​"SMS"​,    
 ​"countryBrandPreferences" ​: [{     
    ​"countryIso"  ​: ​"AE"​,        
    ​"countryName"​ : ​"United Arab Emirates"​,  
       ​"brandId"​     : ​22​,       
    ​"brandName"​   : ​"Bershka"​,     
    ​"communicationCategories" ​: [{     
   ​"optOut"       ​: ​true​,      
  ​ "categoryId"​   : ​8​,       
   ​"categoryName"​ : ​"Newsletter"   
      }]  
   }] 
}

Login with token

Use the login call to retrieve customer details with the token obtained during checkin. The call will retrieve the same details as retrieved through the checkin call. The login call will return all the details about the customer including his/her profile along with the loyalty details (balance, expiry, tier, etc…). Also, the login call will return a session token that needs to be used in all subsequent calls to the API.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as a query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/api/customers/login
{
    "token" : "abc123"
}

EXAMPLE RESPONSE:

{
    "phone"          : "97155239988007",
    "email"          : "john@abc.com",
    "first"          : "John",
    "last"           : "John Sam",
    "nationality"    : "LB",
    "gender"         : "M",
    "birth_date"     : "1970-12-01",
    "profile_set"    : true,//indicates if customer’s profile is set
    "current_credit" : 12.34, // customer’s loyalty balance
    "expires"        : "Aug 9, 2018 7:48:55 AM",//loyalty balance expiry
    "level"          : 1, // customer’s level
    "label"          : "Blue", // customer’s level name
    "level_expires"  : "Aug 9, 2018 7:48:55 AM",//level expiry
    "token"          : "abc123", // customer’s session token
    "tokenExpires"   : "Aug 12, 2017 12:56:02 PM",//session token expiry
    "refreshToken"   : "abc123"//customer’s refresh token
}

Login with OTP

Customers will receive SMS or Email with a short-code (4 digits) to be used during login. This will redirect to a page to verify the code in order to login. After entering the code, it is submitted along with the email or phone previously entered, through the /login API call. This will retrieve all the details about the customer.

Request elements

Requires either phone number or email.

Parameter Type Required Description
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
code Integer Yes OTP received as communication

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/api/customers/login

{
    "phone" : "971557802482",
    "code"  : "1234"
}

EXAMPLE RESPONSE:

{
    "phone"         : "971557802482",
    "email"         : "john@abc.com",
    "first"         : "John",
    "last"          : "Sam",
    "nationality"   : "LB",
    "gender"        : "M",
    "birth_date"    : "1970-12-01",
    "profile_set"   : true,//indicates if customer’s profile is set
    "current_credit": 12.34,//customer’s loyalty balance
    "expires"       : "Aug 9, 2018 7:48:55 AM",//loyalty balance expiry
    "level"         : 1, // customer’s level
    "label"         : "Blue",//customer’s level name
    "level_expires" : "Aug 9, 2018 7:48:55 AM",//level expiry
    "token"         : "abc123",//customer’s session token
    "tokenExpires"  : "Aug 12, 2017 12:56:02 PM",//session token expiry
    "refreshToken"  : "abc123"//customer’s refresh token
}

Save Customer Notes by ID

This call is executed to save the notes added for the customer.

Request elements

Requires either phone number or email ID of the customer.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
notes String Yes New note to be added for the customer

Error messages

Error Code Error Message
1005 Data Not Found 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/accounts/notes?
accountId=f64f2940
{
	notes : "Likes pink nail paint"
}

EXAMPLE RESPONSE:

 {
    "status" : "success"
}

Get Customer Notes by ID

This call is executed to obtain the saved notes added for the customer.

Request elements

Requires either phone number or email ID of the customer.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
notes String Yes New note to be added for the customer

Error messages

Error Code Error Message
1005 Data Not Found 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts/notes?
accountId=f64f2940

EXAMPLE RESPONSE:

 {
  "Well done burger",

"Large fries",

"I like pina colada"

Send Activation Email by ID

This call is executed to send activation email.

Request elements

Requires email ID of the customer.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer

Error messages

Error Code Error Message
1005 Data Not Found 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts/communicate/email?
accountId=f64f2940

EXAMPLE RESPONSE:

 {
    "status" : "success"
}

Send Activation SMS by ID

This call is executed to send activation SMS.

Request elements

Requires phone number of the customer.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer

Error messages

Error Code Error Message
1005 Data Not Found 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts/communicate/sms?
accountId=f64f2940

EXAMPLE RESPONSE:

 {
    "status" : "success"
}

Customer profile

Get customer profile

This call is executed to obtain information about registered customer.

Request elements

Parameter Type Required Description
token String Yes Token received as query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/customer/online/abc123/profiles


EXAMPLE RESPONSE:

 {
    "customer" : {
        "gender"             : "M",
        "first"              : "john",
        "last"               : "Hajj Obeid",
        "phone"              : "971557802482",
        "email"              : "John@abc.com",
        "birth_date"         : "1970-12-01"
        "nationality"        : "LB",
        "country"            : "AE",
        "state_city_emirate" : "LB",
        "home_location"      : "Tecom",
        "work_location"      : "Discovery Gardens",
        "pin"                : "1234"
    }
}

Update customer profile

To update user profile, you will receive an email with a link redirecting to the website, along with a token received as a query parameter. This token value needs to be used with the API call to update customer profile and retrieve existing profile to pre-fill the form.

Request elements

Parameter Type Required Description
token String Yes Token received as query parameter
gender String Yes Gender
first String Yes First name
last String No Last name
phone String Yes Phone number
email String Yes Email
birth_date Date Yes Date of birth
nationality String Yes Nationality
country String Yes Country of residence
state_city_emirate String No State or city or emirate of residence
home_location String No Home location
work_location String No Work location

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/customer/online/abc123/profiles
{
    "customer" : {
        "gender"             : "M",
        "first"              : "John",
        "last"               : "Sam P",
        "phone"              : "971557802482",
        "email"              : "John@abc.com",
        "birth_date"         : "1970-12-01"
        "nationality"        : "LB",
        "country"            : "AE",
        "state_city_emirate" : "LB",
        "home_location"      : "Tecom",
        "work_location"      : "Discovery Gardens",
        "pin"                : "1234"
    }
}

EXAMPLE RESPONSE:
{
    "status" : "SUCCESS"
}

Send Update Profile Email

This call is executed to send an Email after a customer profile is updated.

Request elements

Parameter Type Required Description
email String Yes Email ID of the customer

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/online/email/update_profile

{
    "email": "abc@urbanbuz.com"
    }

EXAMPLE RESPONSE:

{
    "status" : "SUCCESS"
}

Brands

Get brands

This call is executed to obtain all brands registered with a program.

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/brands


EXAMPLE RESPONSE:

{
  "brand_id" ​: ​20​, 
  "name"     ​: ​"Bershka" 
}, 
{ 
 "brand_id" ​: ​21​,
 "name"     ​: ​"Zara" 
}

Get categories

This call is executed to obtain the product categories associated with the brand.

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/online/categories

EXAMPLE RESPONSE:
{
  "id" ​: ​20​, 

  "name" ​: ​"Fashion & Accessories" 

},
 
{ 
"id" ​: ​21​,
 "name"  ​: ​"Beauty&Wellness" 
}

Inventory

Submit item master

This call is executed to create or update an item master.

Request elements

Note: The fields that are not available in the request elements will move under businessFields, as shown in the example request.

Parameter Type Required Description
sku String Yes Alphanumeric code that identifies a product and helps track inventory
name String Yes Name of the product
description String No Detailed description about the product
link String No Link to the product URL (example: e-commerce URL of the product)
image String No Product image URL
brand String No Product brand
gender String No Targeted gender
color String No Product color
country String No Country of origin of the product
inventoryType String No Type of the inventory (example: product/service)
unit String No Type of the unit (example: kg/piece)
unitPrice Decimal No The unit price of the product
businessFields: CATEGORY String No Product category
businessFields: LINE String No Business line of the product

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST

POST http://[subdomain].urbanbuz.com/program/inventory

[
  {
    "sku": "EC-00002-1948574",
    "name": "Apple iPhone Xs",
    "description": "iPhone Xs 256GB Gold",
    "link": "",
    "image": "",
    "brand": "Apple",
    "gender": "UNISEX",
    "color": "Gold",
    "country": "USA",
    "inventoryType": "product",
    "unit": "Piece",
    "unitPrice": "4089",
    "businessFields": {
      "CATEGORY": "Smart Phone",
      "LINE": "Luxury Brand"
    }
  }
]
    
EXAMPLE RESPONSE
 {
     "created":70,
     "updated":20
}

Get transactions by ID

This call is executed to obtain the customer transactions by the IDs generated for the customers.

Request elements

Requires either the phone number or email ID of the customer.

Parameter Type Required Description
receipt String Yes Receipt for the transaction
openTime Date Yes Opentime of the transaction

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

DELETE http://[subdomain].urbanbuz.com/transaction/transactions
{
  "receipt": "123987",
  "openTime": "2017-05-14 10:33:15"
}


EXAMPLE RESPONSE:
class="wikitable"

{
  "status": " SUCCESS"
}

Transaction

Submit Transactions

This call is executed to allow to submit the transactions of customers.

Request elements

Parameter Type Required Description
customer.accountId String Yes Unique ID generated for the customer
customer.phone String Yes Phone number of the customer
customer.email String Yes Email ID of the customer
customer.first String Yes First name of the customer
customer.last String Yes Last name of the customer
receipt String Yes Transaction’s unique identity
openTime Date Yes Transaction’s open time
closeTime Date Yes Transaction’s time of closing
operatorId String No Cashier’s unique identity
operatorName String No Cashier’s name
deviceId String No POS terminal’s unique identity
deviceName String No POS terminal’s name
billed Decimal Yes Transaction’s gross total
paid Decimal Yes Transaction’s net paid
redeemed Decimal Yes Transaction’s net paid in loyalty redemption
billDiscount Decimal Yes Transaction’s total bill level discount
itemDiscountTotal Decimal Yes Transaction’s total item level discount
billTax Decimal Yes Transaction’s total bill level tax
itemTaxTotal Decimal Yes Transaction’s total item level tax
sku String Yes Line item’s unique identifier
qty Decimal Yes Line item’s quantity
unitPrice Decimal Yes Line item’s gross unit price
payments.name String Yes Currency type (e.g. UAE currency)
payments.typeName String Yes Payment type (e.g. Cash)
payments.amount Decimal Yes Payment amount
payments.referenceId String Yes Unique identity of the voucher if voucher is set to true
voucher.name Boolean Yes Voucher reward title
voucher.typeName String Yes Type of redemption
voucher.referenceId String Yes Voucher code
voucher.amount Decimal Yes Value of the voucher
voucher.redemption Boolean Yes True: Indicates that the voucher is redeemable
voucher.voucher Boolean Yes True: Indicates that the voucher has been assigned to the customer
loyalty.name Boolean Yes Loyalty reward title
loyalty.typeName String Yes Type of redemption
loyalty.amount Decimal Yes Amount to be awarded on
loyalty.redemption Boolean Yes True: Indicates that the loyalty points are redeemable
loyalty.voucher Boolean Yes False: Indicates that no voucher has been assigned to the customer
extras.name String Yes Type of additional amount charged to the customer, which is not a product or a service. For example, delivery charges, shipping charges etc
extras.amount Decimal Yes Additional amount charged to the customer, which is not a product purchased. For example: USD 20 as delivery charge indicates charging 20 dollars for delivering the purchased product. Assigning '0' value here indicates there is no extra amount charged to the customer

API Validations on the values

Field Description
itemTaxTotal This should be the total of all the taxes in the items (Sum of items.tax*items.qty)
itemDiscountTotal This should be the total of all the discounts in the items (Sum of items.discount.amount*items.qty)
billed This should be a sum of all items, taxes and extras, that is,

Sum(items.unitPrice*qty)+ Sum(extras.amount)+ billTax+ itemTaxTotal

paid This should be billed-billDiscount-itemDiscountTotal-redeemed

Error messages

Error Code Error Message
1004 The following field is not unique
1006 The following fields are invalid
1002 Fields are empty 
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/transaction/orders/submit
{
 "customer": {
   "accountId": "BSNS-10249",
   "phone": "971581111148",
   "email": "john2091@email.com",
   "first": "John",
   "last": "Samuel"
 },
 "receipt": "BSNS-201705141056",
 "openTime": "2017-05-14 10:33:15",
 "closeTime": "2017-05-14 10:33:15",
 "billed": 1300,
 "paid": 900,
 "redeemed": 200,
 "billDiscount": 0,
 "itemDiscountTotal": 200,
 "billTax": 0,
 "itemTaxTotal": 50,
 "operatorId" : "STAFF001",
 "operatorName" : "Catherine",
 "deviceId" : "POS001",
 "deviceName" : "Front-desk",
 "items": [
   {
     "sku": "SKU-001",
     "name": "Service Name",
     "description": "Service Desc",
     "type": "Service",
     "qty": 1,
     "unit": "Service",
     "unitPrice": 1200,
     "tax": 50,
     "discount": {
       "name": "Name for the Discount",
       "description": "Description for the Discount",
       "amount": 200,
       "groupId": "Discount GroupId",
       "groupName": "Discount Group name",
       "type": "Discount Type",
       "reason": "Discount Reason",
       "authorizedBy": "Branch-Manager"
     }
   },
   {
     "sku": "Zero-001",
     "name": "Zero",
     "description": "Zero level desc",
     "type": "Service",
     "qty": 1,
     "unit": "Service",
     "unitPrice": 0,
     "tax": 0
   }
 ],
 "payments": [
   {
     "name": "Cash",
     "typeName": "Cash",
     "amount": 900,
     "date": "2019-05-14 10:33:15",
     "redemption": false,
     "voucher": false,
     "referenceId": "12685988"
   },
   {
     "name": "50 AED VOUCHER REDEMPTION",
     "typeName": "Voucher",
     "referenceId": "7kwPsl",
     "amount": 50,
     "redemption": true,
     "voucher": true
   },
   {
     "name": "100 LOYALTY REDEMPTION",
     "typeName": "Loyalty Points",
     "amount": 150,
     "redemption": true,
     "voucher": false
   }
 ],
 "extras": [
   {
     "name": "Delivery Charge",
     "amount": 50
   }
 ]
}


EXAMPLE RESPONSE:

{
    "status" : "success"
}

Get transactions by ID

This call is executed to obtain the customer transactions by the IDs generated for the customers.

Request elements

Requires either phone number or email ID of the customer.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
phone Date Yes Phone number of the customer
email Date Yes Email ID of the customer

Error messages

Error Code Error Message
1005 Data Not Found 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/accounts/transactions?
    accountId=f64f2940&phone=971520000000&page=1&size=10


EXAMPLE RESPONSE:

{
  "pageNumber": null,
  "pageSize": null,
  "totalCount": 19,
  "offset": null,
  "totalPages": null,
  "data": [
    {
      "id": null,
      "txnId": "17596956t",
      "receipt": "971551184261-000002",
      "openTime": null,
      "openedAt": "2019-12-09T20:01:04.000+0000",
      "closeTime": null,
      "closedAt": "2019-12-09T20:01:04.000+0000",
      "billed": 500,
      "paid": 500,
      "redeemed": 0,
      "billDiscount": 0,
      "itemDiscountTotal": 0,
      "billTax": 0,
      "itemTaxTotal": 0,
      "status": null,
      "operatorId": null,
      "operatorName": null,
      "deviceId": null,
      "deviceName": null,
      "revision": null,
      "items": [
        {
          "categories": null,
          "custom_properties": null,
          "area_id": "405",
          "area_name": "Area 1",
          "branch_id": "111",
          "branch_name": "Branch 1",
          "brand_category_id": "101",
          "brand_category_label": "ABC",
          "brand_id": "10",
          "brand_name": "AAA",
          "city": "City 1",
          "city_iso": "CT-01-12345",
          "country": "country 1",
          "country_iso": "CN",
          "channel_name": "PoS",
          "sku": "0001111110",
          "item_name": "65051774:LADY MILLION EDP 50ML",
          "item_description": "NULL",
          "item_category_id": "NULL",
          "item_category_name": "NULL",
          "item_sub_category_id": "NULL",
          "item_sub_category_name": "NULL",
          "item_type": "P",
          "item_qty": "1.000",
          "item_unit": null,
          "item_unit_price": "100.000",
          "item_eq_unit_price": "27.0",
          "item_tax": "0.000",
          "item_eq_tax": "0.0",
          "item_total_amount": "100.000",
          "item_eq_total_amount": "27.0",
          "item_total_amount_wo_tax": "100.000",
          "item_eq_total_amount_wo_tax": "27.0",
          "item_discount": "0.000",
          "item_eq_discount": "0.0",
          "item_sold_on": "2019-12-09 20:01:04",
          "item_sold_on_year": "2019",
          "item_sold_on_month": "December",
          "item_sold_on_day": "Monday",
          "inv_item_color": "NULL",
          "inv_item_gender": "NULL",
          "inv_country": "NULL",
          "inv_brand": "NULL",
          "inv_type": "NULL",
          "inv_item_name": "NULL",
          "inv_item_link": "NULL",
          "inv_item_description": "NULL",
          "inv_item_size": null,
          "product_id": null
        }
      ],
      "payments": [
        {
          "type_name": "Cash",
          "amount": "500.000",
          "reference_id": null,
          "redemption": "false",
          "type_id": null,
          "name": null,
          "payment_at": null
        }
      ],
      "modification": null,
      "linesChanged": null,
      "paymentsChanged": null,
      "oldItems": null,
      "brand": "AAA",
      "branch": "Branch 1",
      "country": "country 1"
    },
    {
      "id": null,
      "txnId": "17596957t",
      "receipt": "971551184261-000003",
      "openTime": null,
      "openedAt": "2019-12-09T20:01:04.000+0000",
      "closeTime": null,
      "closedAt": "2019-12-09T20:01:04.000+0000",
      "billed": 500,
      "paid": 500,
      "redeemed": 0,
      "billDiscount": 0,
      "itemDiscountTotal": 0,
      "billTax": 0,
      "itemTaxTotal": 0,
      "status": null,
      "operatorId": null,
      "operatorName": null,
      "deviceId": null,
      "deviceName": null,
      "revision": null,
      "items": [
        {
          "categories": null,
          "custom_properties": null,
          "area_id": "405",
          "area_name": "Area 1",
          "branch_id": "111",
          "branch_name": "Branch 1",
          "brand_category_id": "101",
          "brand_category_label": "ABC",
          "brand_id": "10",
          "brand_name": "AAA",
          "city": "City 1",
          "city_iso": "CT-01-12345",
          "country": "country 1",
          "country_iso": "CN",
          "channel_name": "PoS",
          "sku": "0001111110",
          "item_name": "65051774:LADY MILLION EDP 50ML",
          "item_description": "NULL",
          "item_category_id": "NULL",
          "item_category_name": "NULL",
          "item_sub_category_id": "NULL",
          "item_sub_category_name": "NULL",
          "item_type": "P",
          "item_qty": "1.000",
          "item_unit": null,
          "item_unit_price": "100.000",
          "item_eq_unit_price": "27.0",
          "item_tax": "0.000",
          "item_eq_tax": "0.0",
          "item_total_amount": "100.000",
          "item_eq_total_amount": "27.0",
          "item_total_amount_wo_tax": "100.000",
          "item_eq_total_amount_wo_tax": "27.0",
          "item_discount": "0.000",
          "item_eq_discount": "0.0",
          "item_sold_on": "2019-12-09 20:01:04",
          "item_sold_on_year": "2019",
          "item_sold_on_month": "December",
          "item_sold_on_day": "Monday",
          "inv_item_color": "NULL",
          "inv_item_gender": "NULL",
          "inv_country": "NULL",
          "inv_brand": "NULL",
          "inv_type": "NULL",
          "inv_item_name": "NULL",
          "inv_item_link": "NULL",
          "inv_item_description": "NULL",
          "inv_item_size": null,
          "product_id": null
        },
        {
          "categories": null,
          "custom_properties": null,
          "area_id": "405",
          "area_name": "Area 1",
          "branch_id": "111",
          "branch_name": "Branch 1",
          "brand_category_id": "101",
          "brand_category_label": "ABC",
          "brand_id": "10",
          "brand_name": "AAA",
          "city": "City 1",
          "city_iso": "CT-01-12345",
          "country": "country 1",
          "country_iso": "CN",
          "channel_name": "PoS",
          "sku": "005310035898",
          "item_name": "82270:JASMIN NOIR EDP 50ML",
          "item_description": "NULL",
          "item_category_id": "NULL",
          "item_category_name": "NULL",
          "item_sub_category_id": "NULL",
          "item_sub_category_name": "NULL",
          "item_type": "P",
          "item_qty": "2.000",
          "item_unit": null,
          "item_unit_price": "200.000",
          "item_eq_unit_price": "54.0",
          "item_tax": "0.000",
          "item_eq_tax": "0.0",
          "item_total_amount": "400.000",
          "item_eq_total_amount": "108.0",
          "item_total_amount_wo_tax": "400.000",
          "item_eq_total_amount_wo_tax": "108.0",
          "item_discount": "0.000",
          "item_eq_discount": "0.0",
          "item_sold_on": "2019-12-09 20:01:04",
          "item_sold_on_year": "2019",
          "item_sold_on_month": "December",
          "item_sold_on_day": "Monday",
          "inv_item_color": "NULL",
          "inv_item_gender": "NULL",
          "inv_country": "NULL",
          "inv_brand": "NULL",
          "inv_type": "NULL",
          "inv_item_name": "NULL",
          "inv_item_link": "NULL",
          "inv_item_description": "NULL",
          "inv_item_size": null,
          "product_id": null
        }
      ],
      "payments": [
        {
          "type_name": "Cash",
          "amount": "500.000",
          "reference_id": null,
          "redemption": "false",
          "type_id": null,
          "name": null,
          "payment_at": null
        }
      ],
      "modification": null,
      "linesChanged": null,
      "paymentsChanged": null,
      "oldItems": null,
      "brand": "AAA",
      "branch": "Branch 1",
      "country": "country 1"
    },
    {
      "id": null,
      "txnId": "17596959t",
      "receipt": "971551184261-000004",
      "openTime": null,
      "openedAt": "2019-12-09T20:01:04.000+0000",
      "closeTime": null,
      "closedAt": "2019-12-09T20:01:04.000+0000",
      "billed": 500,
      "paid": 500,
      "redeemed": 0,
      "billDiscount": 0,
      "itemDiscountTotal": 0,
      "billTax": 0,
      "itemTaxTotal": 0,
      "status": null,
      "operatorId": null,
      "operatorName": null,
      "deviceId": null,
      "deviceName": null,
      "revision": null,
      "items": [
        {
          "categories": null,
          "custom_properties": null,
          "area_id": "405",
          "area_name": "Area 1",
          "branch_id": "111",
          "branch_name": "Branch 1",
          "brand_category_id": "101",
          "brand_category_label": "ABC",
          "brand_id": "10",
          "brand_name": "AAA",
          "city": "City 1",
          "city_iso": "CT-01-12345",
          "country": "country 1",
          "country_iso": "CN",
          "channel_name": "PoS",
          "sku": "000110051010",
          "item_name": "65051774:LADY MILLION EDP 50ML",
          "item_description": "NULL",
          "item_category_id": "NULL",
          "item_category_name": "NULL",
          "item_sub_category_id": "NULL",
          "item_sub_category_name": "NULL",
          "item_type": "P",
          "item_qty": "1.000",
          "item_unit": null,
          "item_unit_price": "100.000",
          "item_eq_unit_price": "27.0",
          "item_tax": "0.000",
          "item_eq_tax": "0.0",
          "item_total_amount": "100.000",
          "item_eq_total_amount": "27.0",
          "item_total_amount_wo_tax": "100.000",
          "item_eq_total_amount_wo_tax": "27.0",
          "item_discount": "0.000",
          "item_eq_discount": "0.0",
          "item_sold_on": "2019-12-09 20:01:04",
          "item_sold_on_year": "2019",
          "item_sold_on_month": "December",
          "item_sold_on_day": "Monday",
          "inv_item_color": "NULL",
          "inv_item_gender": "NULL",
          "inv_country": "NULL",
          "inv_brand": "NULL",
          "inv_type": "NULL",
          "inv_item_name": "NULL",
          "inv_item_link": "NULL",
          "inv_item_description": "NULL",
          "inv_item_size": null,
          "product_id": null
        }
      ],
      "payments": [
        {
          "type_name": "Cash",
          "amount": "500.000",
          "reference_id": null,
          "redemption": "false",
          "type_id": null,
          "name": null,
          "payment_at": null
        }
      ],
      "modification": null,
      "linesChanged": null,
      "paymentsChanged": null,
      "oldItems": null,
      "brand": "AAA",
      "branch": "Branch 1",
      "country": "country 1"
    }
  ]
}

Cancel transaction

This call is executed to allow to cancel/delete an existing transaction. The transaction receipt will be the key for the cancellation.

Request elements

Parameter Type Required Description
receipt String Yes Receipt for the transaction
openTime Date Yes Opentime of the transaction

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

DELETE http://[subdomain].urbanbuz.com/transaction/transactions
{
  "receipt": "123987",
  "openTime": "2017-05-14 10:33:15"
}


EXAMPLE RESPONSE:
{
  "status": " SUCCESS"
}

Loyalty

Get loyalty posting by account ID

A loyalty posting is a record of the points credited and debited to an account. This call is executed to obtain the list of points credited and debited to an account, and also the tier details of the member. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email ID of the customer.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST: 
GET http://[subdomain].urbanbuz.com/program/loyalty/
    posting?accountId=f64f2940-fae4-11e7-8c5f-ef697603


EXAMPLE RESPONSE:
[
  {
    "id": 697603,
    "tierOrder": 1,
    "progId": 11,
    "userId": 6459979,
    "triggerId": 11,
    "triggerName": "Visits",
    "tierName": "Tier name",
    "credit": 500,
    "creditValue": 10,
    "debit": 0,
    "debitValue": 0,
    "currency": "AED",
    "postingDate": "2018-05-25 07:30:16 UTC",
    "txnDate": "2018-05-25 00:00:00 UTC",
    "receipt": "585720",
    "branchId": 838,
    "branchName": "Branch name",
    "brandId": 76,
    "brandName": "Brand name",
    "countryIso": "AE",
    "country": "United Arab Emirates",
    "type": 2
}
]

Send OTP and validate redemption

This call is executed to generate OTP for validating the redemption.

Request elements

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer
redemption.value BigDecimal Yes Value of the Redemption

Error messages

Error Code Error Message
1006 The following fields are invalid 
EXAMPLE REQUEST:
 
POST http://[subdomain].urbanbuz.com/program/accounts/otp/loyalty
{
  "accountId": "ba215440-430d-11e8-842f-0ed5f89f718b",
  "redemption": {
    "value": "16.5"
  }
}

EXAMPLE RESPONSE:

 {
  "status": "success",
  "otp": "2459",
  "redemption": {
    "point": "1650",
    "value": "16.5"
  },
  "loyalty": {
    "program": {
      "name": "Loyalty Program Name",
      "logo": "URL path to image.jpg"
    },
    "tier": {
      "name": "Loyalty Tier 1",
      "logo": "URL path to image.jpg",
      "order": 1,
      "expiry": "2019-01-01"
    },
    "wallets": [
      {
        "countryIso": "AE",
        "currency": "AED",
        "point": 1570,
        "value": 15.75
      }
    ],
      "redeemable": {
      "point": 1000,
      "value": 10,
      "currency": "AED"
  },
   "expiry": {
      "point": 256,
      "date": "2018-07-03"
  },
  "reason": null
}

EXAMPLE RESPONSE (FAILURE)

 {
  "status": "failure",
  "reason": {
    "errorCode": "1017",
    "errorMessage": "Insufficient points"
  },
  "otp": null,
  "loyalty": {
    "program": {
      "name": "Loyalty Program Name",
      "logo": "URL path to image.jpg"
    },
    "tier": {
      "name": "Loyalty Tier 1",
      "logo": "URL path to image.jpg",
      "order": 1,
      "expiry": "2018-01-01"
    },
    "wallets": [
      {
        "countryIso": "AE",
        "currency": "AED",
        "point": 1575,
        "value": 15.75,
        "expiry": "2018-05-03"
      }
    ]
  }
}

Vouchers

Get vouchers of customer

This call is executed to obtain the list of all vouchers associated with a particular customer, which includes Available, Expired, and Already Used vouchers for that customer.

Request elements

Parameter Type Required Description
token String Yes Customer’s token received as a query parameter

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:
GET http://[subdomain].urbanbuz.com/online/{token}/vouchers

EXAMPLE RESPONSE:

 {
    "title"   : "Voucher A",
    "icon"    : "https://urbanbuz.com/images/vouchera.jpg",
    "code"    : "7bf147",
    "issued"  : "2018-01-01",
    "expires" : "2018-02-01",
    "value"     : "20",
    "valueType" : "percentage",
    "status"    : "active"
}, {
    "title"     : "Voucher B",
    "icon"      : "https://urbanbuz.com/images/voucherb.jpg",
    "code"      : "e3a962",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "100",
    "valueType" : "fixed",
    "status"    : "expired"
}, {
    "title"     : "Voucher C",
    "icon"      : "https://urbanbuz.com/images/voucherc.jpg",
    "code"      : "5b103c",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "10",
    "valueType" : "percentage",
    "status"    : "redeemed",
    "redeemed"  : "2017-12-30 12:34:56",
    "redeemedBranch" : {
        "name"       : "Dubai Mall",
        "brandName"  : "Brand A"
    }
}

Get vouchers by account ID

This call is executed to obtain the list of vouchers by account ID. The parameters of this call are dynamic based on the business setup of the account’s profile.

Request elements

Requires either phone number or email.

Parameter Type Required Description
accountId String Yes Unique ID generated for the customer

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

GET http://[subdomain].urbanbuz.com/program/vouchers?accountId=f64f2940
    

EXAMPLE RESPONSE:

[{
    "title"     : "Voucher A",
    "icon"      : "https://urbanbuz.com/images/vouchera.jpg",
    "code"      : "7bf147",
    "issued"    : "2018-01-01",
    "expires"   : "2018-02-01",
    "value"     : "20",
    "valueType" : "percentage",
    "status"    : "active"
}, {
    "title"     : "Voucher B",
    "icon"      : "https://urbanbuz.com/images/voucherb.jpg",
    "code"      : "e3a962",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "100",
    "valueType" : "fixed",
    "status"    : "expired"
}, {
    "title"     : "Voucher C",
    "icon"      : "https://urbanbuz.com/images/voucherc.jpg",
    "code"      : "5b103c",
    "issued"    : "2017-01-01",
    "expires"   : "2018-01-01",
    "value"     : "10",
    "valueType" : "percentage",
    "status"    : "redeemed",
    "redeemed"  : "2017-12-30 12:34:56",
    "redeemedBranch" : {
        "name"       : "Dubai Mall",
        "brandName"  : "Brand A"
    }
}]

Order

Submit order

This call is executed to allow to submit a new order.

Request elements

Parameter Type Required Description
customer.accountId String Yes Unique ID generated for the customer
customer.phone String Yes Phone number of the customer
customer.email String Yes Email ID of the customer
customer.first String Yes First name of the customer
customer.last String Yes Last name of the customer
receipt String Yes Transaction’s unique identity
openTime Date Yes Transaction’s open time
closeTime Date Yes Transaction’s time of closing
operatorId String No Cashier’s unique identity
operatorName String No Cashier’s name
deviceId String No POS terminal’s unique identity
deviceName String No POS terminal’s name
billed Decimal Yes Transaction’s gross total
paid Decimal Yes Transaction’s net paid
redeemed Decimal Yes Transaction’s net paid in loyalty redemption
billDiscount Decimal Yes Transaction’s total bill level discount
itemDiscountTotal Decimal Yes Transaction’s total item level discount
billTax Decimal Yes Transaction’s total bill level tax
itemTaxTotal Decimal Yes Transaction’s total item level tax
sku String Yes Line item’s unique identifier
qty Decimal Yes Line item’s quantity
unitPrice Decimal Yes Line item’s gross unit price
payments.name String Yes Currency type (e.g. UAE currency)
payments.typeName String Yes Payment type (e.g. Cash)
payments.amount Decimal Yes Payment amount
payments.referenceId String Yes Unique identity of the voucher if voucher is set to true
voucher.name Boolean Yes Voucher reward title
voucher.typeName String Yes Type of redemption
voucher.referenceId String Yes Voucher code
voucher.amount Decimal Yes Value of the voucher
voucher.redemption Boolean Yes True: Indicates that the voucher is redeemable
voucher.voucher Boolean Yes True: Indicates that the voucher has been assigned to the customer
loyalty.name Boolean Yes Loyalty reward title
loyalty.typeName String Yes Type of redemption
loyalty.amount Decimal Yes Amount to be awarded on
loyalty.redemption Boolean Yes True: Indicates that the loyalty points are redeemable
loyalty.voucher Boolean Yes False: Indicates that no voucher has been assigned to the customer
extras.name String Yes Type of additional amount charged to the customer, which is not a product or a service. For example, delivery charges, shipping charges etc
extras.amount Decimal Yes Additional amount charged to the customer, which is not a product purchased. For example: USD 20 as delivery charge indicates charging 20 dollars for delivering the purchased product. Assigning '0' value here indicates there is no extra amount charged to the customer

API Validations on the values

Field Description
itemTaxTotal This should be the total of all the taxes in the items (Sum of items.tax*items.qty)
itemDiscountTotal This should be the total of all the discounts in the items (Sum of items.discount.amount*items.qty)
billed This should be a sum of all items, taxes and extras, that is,

Sum(items.unitPrice*qty)+ Sum(extras.amount)+ billTax+ itemTaxTotal

paid This should be billed-billDiscount-itemDiscountTotal-redeemed

Error messages

Error Code Error Message
1004 The following field is not unique
1006 The following fields are invalid
1002 Fields are empty 
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/transaction/orders/submit
{
 "customer": {
   "accountId": "BSNS-10249",
   "phone": "971581111148",
   "email": "john2091@email.com",
   "first": "John",
   "last": "Samuel"
 },
 "receipt": "BSNS-201705141056",
 "openTime": "2017-05-14 10:33:15",
 "closeTime": "2017-05-14 10:33:15",
 "billed": 1300,
 "paid": 900,
 "redeemed": 200,
 "billDiscount": 0,
 "itemDiscountTotal": 200,
 "billTax": 0,
 "itemTaxTotal": 50,
 "operatorId" : "STAFF001",
 "operatorName" : "Catherine",
 "deviceId" : "POS001",
 "deviceName" : "Front-desk",
 "items": [
   {
     "sku": "SKU-001",
     "name": "Service Name",
     "description": "Service Desc",
     "type": "Service",
     "qty": 1,
     "unit": "Service",
     "unitPrice": 1200,
     "tax": 50,
     "discount": {
       "name": "Name for the Discount",
       "description": "Description for the Discount",
       "amount": 200,
       "groupId": "Discount GroupId",
       "groupName": "Discount Group name",
       "type": "Discount Type",
       "reason": "Discount Reason",
       "authorizedBy": "Branch-Manager"
     }
   },
   {
     "sku": "Zero-001",
     "name": "Zero",
     "description": "Zero level desc",
     "type": "Service",
     "qty": 1,
     "unit": "Service",
     "unitPrice": 0,
     "tax": 0
   }
 ],
 "payments": [
   {
     "name": "Cash",
     "typeName": "Cash",
     "amount": 900,
     "date": "2019-05-14 10:33:15",
     "redemption": false,
     "voucher": false,
     "referenceId": "12685988"
   },
   {
     "name": "50 AED VOUCHER REDEMPTION",
     "typeName": "Voucher",
     "referenceId": "7kwPsl",
     "amount": 50,
     "redemption": true,
     "voucher": true
   },
   {
     "name": "100 LOYALTY REDEMPTION",
     "typeName": "Loyalty Points",
     "amount": 150,
     "redemption": true,
     "voucher": false
   }
 ],
 "extras": [
   {
     "name": "Delivery Charge",
     "amount": 50
   }
 ]
}


EXAMPLE RESPONSE:

{
    "status" : "success"
}

Update order status

This call is executed to allow to update the status of the order placed (Confirmed/Dispatched/Delivered/Canceled).

Request elements

Parameter Type Required Description
receipt String Yes Transaction’s unique identifier
status Decimal Yes Status of the placed order

Error messages

Error Code Error Message
1004 The following field is not unique
1006 The following fields are invalid
1002 Fields are empty 
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com/transaction/orders/status
{
    "receipt"           : "REC-001",
    "status"            : "confirmed"
}

EXAMPLE RESPONSE:
 {
    "status" : "success"
}

Appointment

Submit appointment

This call is executed to allow to submit the appointment that has been made. Validations:

  • Reference number should be mandatory and unique across branches.
  • Customer object should have any of the following identifiers: phone/email/customerId
  • Line items of the appointment should be added to the “items” array of line item object.
  • “Sku” should be mandatory for each line item.

Request elements

Parameter Type Required Description
customer_id String Yes Unique identity assigned to the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
referenceNumber String Yes Reference number for the appointment made
generated Date Yes Date and time when the appointment was made and registered
start Date Yes Start date and time of the appointment
end Date Yes End date and time of the appointment
rebooking Boolean Yes False indicates no rebooking is permitted for the booked appointment
operatorId String Yes ID of the staff who recorded the appointment
operatorName String Yes Name of the staff who recorded the appointment
deviceId String Yes ID of the device that was used to register the appointment
deviceName String Yes Name of the device that was used to register the appointment
status Boolean Yes open/confirmed/closed/canceled/no-show/deleted: Status of the booked appointment
receipt String Yes The appointment receipt
source String Yes The medium through which the appointment was made (online booking)
sku String Yes Unique identifier for the service purchased (appointment)
name String Yes Name of the consulting doctor
duration String Yes Duration of the appointment
consultantId String Yes Unique identity of the consulting doctor
consultantName String Yes Name of the consulting doctor
consultantType String Yes Type of consultant (doctor)

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com//appointments/submit
{
  "customer": {
	"customer_id": "BSNS-10249",
	"phone": "971581111148",
	"email": "jhon2@email.com"
  },
  "referenceNumber": "APPO-2017-10-19-001",
  "generated": "2017-10-22 10:33:15",
"start": "2017-11-14 10:00:00",
  "end": "2017-11-14 11:00:00",
  "rebooking": false,
  "operatorId": "Moo-Foo",
  "operatorName": "Moo Operator",
  "deviceId": "Foo Device",
  "deviceName": "Foo Device Name",
  "status": "open/confirmed/closed/canceled/no-show/deleted",
  "checkin": "2017-05-14 10:33:15",
  "receipt": "BSNS-201705141056",
  "source": "Online Booking",
  "items": [
	{
  	"sku": "DR-CONSU-001",
  	"name": "Doctor Consultant",
  	"start": "2017-11-14 10:00:00",
  	"end": "2017-11-14 11:00:00",
  	"duration": 30,
  	"consultantId": "DR-001",
  	"consultantName": "John",
            "consultantType": "Doctor"
	}
  ]
}
}


EXAMPLE RESPONSE:
 {
    "status" : "success"
}

Update appointment status

This call is executed to change the status of an existing transaction. The reference number will be the key for the update.

Request elements

Parameter Type Required Description
customer_id String Yes Unique identity assigned to the customer
phone String Yes Phone number of the customer
email String Yes Email ID of the customer
referenceNumber String Yes Reference number for the appointment made
checkin String Yes Checkin by the customer
status String Yes Status of the appointment (closed)

Error messages

Error Code Error Message
400 Bad request
401 Not authorized
500 Internal server error 
EXAMPLE REQUEST:

PUT http://[subdomain].urbanbuz.com//appointments/submit
{
 "customer": {
	"customer_id": "BSNS-10249",
	"phone": "971581111148",
	"email": "jhon2@email.com"
  },
  "referenceNumber": "BSNS-201705141033",
  "checkin": "2017-05-14 10:33:15",
  "status": "closed"
}
|}

EXAMPLE RESPONSE:

 {
    "status" : "success"
}

Reports

The following sections describe the reporting API calls.

Fetch accounts

This call lets you obtain the list of accounts (with the details of the account) within a given time range.

Request elements

Parameter Type Required Description
start Date Yes Start date and start time of retrieving data
end Date Yes End date and end time of retrieving data

Error messages

Error Code Error Message
1005 No data found in the database for the sent request parameters 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/
     reports/accounts?page=1&size=10
{
 "start": "2017-05-14 10:33:15",
"end": "2017-05-14 10:33:15
}


EXAMPLE RESPONSE:

 {
"pageNumber": 1,
"pageSize": 3,
"totalCount": 2242,
"data": [
{
"profile": {
"phone": "971500000000",
"email": null,
"accountId": "ABCD",
"first": "John",
"last": "Brit",
"birthdate": "1986-04-05",
"gender": "M",
"city": null,
"country": null,
"nationality": null,
"language": null,
"businessFields": {
"title": "Mr.",
"ethnicity": "America"
}
},
"originated": {
"brand": "ABC",
"name": "ABC-Mall",
"branchCode": "2000",
"countryName": "United Arab Emirates",
"countryIso": "AE"
}
}
]
}

Fetch vouchers

Voucher is a type of a reward provided to customers. You can create vouchers to award your customers based on different criteria and to encourage a certain behavior. This API fetches the voucher issued/redeemed/expired within a given time range.

Request elements

Parameter Type Required Description
start String Yes Start date to fetch the vouchers
end String Yes End date to fetch the vouchers

Response elements

Parameter Type Required Description
code String Yes This is the voucher code
issued Date Yes Issued date of the voucher
redeemed Date No Redeemed date if the voucher is redeemed
expiry Date Yes Expiry date of the voucher
enabled boolean Yes True for enabled, false for disabled
issuedBranch Object Yes Details of the branch issuing the voucher
redeemedBranch Object No Branch details where the voucher was redeemed
campaign Object No Campaign title for which the voucher was issued
reward Object No Reward title for which the voucher was issued
voucher Object Yes Voucher details
voucher.title String Yes Voucher title
valueFixed Integer No Value if it is a fixed value voucher
valueDiscount Integer No Discount in percentage
redeemableBranchList Object No List of branches where voucher can be redeemed
country Object Yes Country for which the voucher was setup
brand Object Yes Brands for which the voucher was setup
customer Object Yes Details of the customer (phone/email/customer ID) to whom the voucher is issued

Error messages

Error Code Error Message
400 Bad request
404 Given Resource not found 
EXAMPLE REQUEST:

POST http://api3.urbanbuz.com/program/reports/vouchers?page=1&size=100
{
   "start" : "2018-04-24 16:00:00",
   "end" : "2018-04-24 16:10:00"
}

EXAMPLE RESPONSE:

 {
   "pageNumber": 1,
  "pageSize": 100,
  "totalCount": 8,
  "offset": 0,
  "data": [
    {
      "id": 0,
      "code": "2cJRhV",                  
      "issued": "2018-04-24 16:07:00",    
      "redeemed": null,       
      "expires": "2019-04-24 16:07:00",  
      "enabled": true,
      "issuedBranch": {
         "brand": "ABC",
         "name": "ABC-Mall",
         "branchCode": "2000",
         "countryIso": "AE",
       },
      "redeemedBranch": null,
      "campaign": {
         "title": "First Shopping voucher"
       }
      "reward": {
         "title": "First Shopping reward"
       },
      "voucher": {
        "title": "AED 100 Voucher UAE",     
        "icon": "https://newcem.urbanbuz.com/upload/images/xxx.png",
        "valueFixed": 0,
        "valueDiscount": 10,                
        "redeemableBranchList": [
         {
         "brand": "ABC",
         "name": "ABC-Mall",
         "branchCode": "S069",
         "countryIso": "AE",
         },
         {
         "brand": "ABC",
         "name": "ABC-Mall2",
         "branchCode": "2001",
         "countryIso": "AE",
        }
        ],
        "country": {
          "countryIso": "AE",
          "countryName": "United Arab Emirates"
        },
        "brands": [
          "Brands",
          "POP"
        ]
      },
      "customer": {  
        "phone": "971500000000",
        "email": "ABC@hotmail.com",
        "customerId": "10000"
      }
    }
  ]
}

Fetch transactions

This call lets you obtain the transaction report for the specified time range.


Request elements

Parameter Type Required Description
start Date Yes Start date and time
end Date Yes End date and time

Error messages

Error Code Error Message
1005 Data not found 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/
     reports/transactions?page=1&size=10
{
  "start": "2017-05-14 10:33:15",
  "end": "2017-05-14 10:33:15
}

EXAMPLE RESPONSE:

 {
  "pageNumber": 1,
  "pageSize": 1,
  "totalCount": 28,
  "offset": 0,
  "data": [
    {
      "transaction": {
        "receipt": "971552456810-18",
        "openedAt": "2018-01-22 13:59:00",
        "closedAt": null,
        "billed": 210,
        "paid": 100,
        "redeemed": 0,
        "billDiscount": 0,
        "itemDiscountTotal": 0,
        "billTax": 0,
        "itemTaxTotal": 0,
        "operatorId": null,
        "operatorName": null,
        "deviceId": "T004",
        "deviceName": "ABC COUNTER 1",
        "items": [
          {
            "id": null,
            "sku": "S2597",
            "name": "SUIT2/375",
            "description": null,
            "type": "P",
            "inventoryId": null,
            "inventoryCategoryId": null,
            "qty": 1,
            "unit": null,
            "unitPrice": 60,
            "tax": null,
            "lineAmount": 60,
            "discount": null,
            "customFields": null
          },
          {
            "id": null,
            "sku": "S2600",
            "name": "SUIT2/895",
            "description": null,
            "type": "P",
            "inventoryId": null,
            "inventoryCategoryId": null,
            "qty": 1,
            "unit": null,
            "unitPrice": 100,
            "tax": null,
            "lineAmount": 100,
            "discount": null,
            "customFields": null
          },
          {
            "id": null,
            "sku": "S2599",
            "name": "SUIT2/585",
            "description": null,
            "type": "P",
            "inventoryId": null,
            "inventoryCategoryId": null,
            "qty": 2,
            "unit": null,
            "unitPrice": 25,
            "tax": null,
            "lineAmount": 50,
            "discount": null,
            "customFields": null
          }
        ],
        "payments": [
          {
            "id": null,
            "name": null,
            "typeId": null,
            "typeName": "Master Card",
            "date": null,
            "paymentAt": null,
            "amount": 100,
            "referenceId": null,
            "redemption": false,
            "customFields": null
          }
        ],
        "extras": null,
        "customFields": null
      }
    }
  ]
}

Fetch and export campaigns

This call is executed to retrieve all the details pertaining to a scheduled campaign (SMS campaign or Email campaign) and export these details to obtain the statistics of the scheduled campaigns. The campaign details mainly include:

  • Campaign scheduled date
  • Location where the campaign is scheduled
  • Count of sent, delivered and undelivered campaigns, and so on.


Request elements

Parameter Type Required Description
start Date Yes Start date and start time of the SMS/Email campaign schedule
end Date Yes End date and end time of the SMS/Email campaign schedule
resultEndPoint String Yes The endpoint to update when the result is ready
export Boolean Yes To obtain the statistics of the scheduled campaign in the form of a csv file structure.

Error messages

Error Code Error Message
1005 No data found in the database for the sent request parameters 
EXAMPLE REQUEST:

POST http://[subdomain].urbanbuz.com/program/reports/campaigns?export=true
{
  "start": "2018-09-10 00:00:00",
  "end": "2018-09-10 23:59:59,
  "resultEndPoint": "https://[subdomain].urbanbuz.com/campaigns/results"
}

'''Example request''' that generates the csv file 
(displaying the details of the campaign) when the parameter value 
'''export''' is set to be '''true'''.

 POST http://company.com/campaigns/results

{
"jobId": "a1fTstz347",
"status": "Generated",
"fileName": Campaign_SMS_a1fTstz347_20180909.csv",
}

EXAMPLE RESPONSE:

{  
  "totalCount": 6,
  "status": "Generating",
  "fileName": "Campaign_SMS_a1fTstz347_20180909.csv",  
  "jobId":1246789454645,
  "data": [
    {
      "campaignId": "a1fTstz347",
      "campaignDescription":"Discount on bags"
      "channel": "SMS",
      "scheduled": "2018-09-09 14:00:00",
      "lastUpdated":"2018-09-10 11:25:00",
      "timeZone": "Asia/Dubai",
      "sent": "15000",
      "delivered": "13000",
      "undelivered": "2000",
      "filters": {
        "location": {
          "country": [{
              "countryIso": "AE",
              "name": "United Arab Emirates"
            }
          ],
          "brand": [{
              "name": "Elann"
            }
          ],
          "profile": [{
              "phoneCountry": "AE"
            },
            {
              "gender": "M"
            }
          ],
          "transaction": [{
              "active": {
                "from": "2017-01-01"
              }
            }
          ]
        }
      }
    }
  ]
}

Status code and error messages

API requests can at times result in errors and return appropriate status code that help you identify the error type.

The following table describes standard error codes returned by the APIs:

Status code Text Description
200 OK Indicates that the request was correct and sent to the core for further processing.
400 Bad request Indicates that the request does not contain all the information/ parameters in order to proceed. This

error is returned from the Resource class. Domain validation errors, missing data, etc. are some examples.

401 Not authorized Indicates that the request was not authorized and cannot proceed. This error code is

returned from Authentication Filter class.

500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

This need to be analyzed further.

The following table describes the standard error codes returned by UrbanBuz APIs.

Error code Description
1001 The request payload is empty
1002 Certain field values are empty
1003 Internal Server Error
1004 Certain fields are not unique
1005 No data found in the database for the sent request parameters
1009 No data found in the database for the sent request parameters
1010 At least one of the fields required to be filled

Timestamp

Timestamps are returned in the UTC format: YYYY-MM-DDTHH:MM:SSZ

Retrieved from "https://developer.urbanbuz.com/api/index.php?title=Main_Page&oldid=654"