Skip to content

Commerce flow API

COMMERCE FLOW API, custom store API, catalog API, create order API

Use these endpoints to enable the commerce flow on your WhatsApp bot through APIs. BusinessOnBot calls them to show your categories, products and variants in WhatsApp, and to create and place orders.

Method Endpoint What it does
GET {{domain_name}}/categories Get all categories
GET {{domain_name}}/categories/:categoryId/products Get products by category ID
GET {{domain_name}}/products/:productId Get a product and its variants by product ID
GET {{domain_name}}/products Get all products and variants
GET {{domain_name}}/variants/:variantId Get a variant by variant ID
PUT {{domain_name}}/products/:productId Update the tags of a product
POST {{domain_name}}/create-order Create a draft order
POST {{domain_name}}/place-order Place the order (status to processing)

Contact support@businessonbot.com to get your guest API key and URL.

The API documentation is intended to be used as a reference to communicate with BusinessOnBot. BusinessOnBot will be calling the customer’s APIs with the request specified in the documentation and expects responses as mentioned.

For all the APIs, BusinessOnBot will be passing the API KEY with the custom http header ‘x-guest-id’.

Each endpoint’s success response is shown below. Errors are returned as JSON with a status, a statusCode and an error message:

status statusCode Meaning
failure 400 Bad payload or bad request
failure 500 Internal server error

Method: GET

URL: {{domain_name}}/categories

{
id: <string> (unique identifier for the category),
title: <string> (title of the category)
}
[
{
"id": "6862294089884",
"title": "Chocolates"
},
{
"id": "6862294349884",
"title": "Cakes"
}
]
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
},
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Method: GET

URL: {{domain_name}}/categories/:categoryId/products

NOTE: A product can be present in multiple categories. NOTE: Some products can have different options like different colors and sizes. In this case the same product with different colors should be served with unique product IDs. Example: A shirt has blue and black color and e different sizes each. In this case Blue shirt and black shirt will have unique product Ids, and their variants would be sizes.

{
"id": "<string>",
"title": "<string>",
"status": "ACTIVE | <inactive>",
"tags": ["<string>"]
}
[
{
"id": "6862294089884",
"title": "Chocolates"
},
{
"id": "6862294349884",
"title": "Cakes"
}
]
[
{
"id": "6862294089884",
"title": "Chocolates"
},
{
"id": "6862294349884",
"title": "Cakes"
}
]

Method: GET

URL: {{domain_name}}/products/:productId

{
"id": "<string>", // Unique identifier for the product
"title": "<string>", // Title of the product
"image": "<string>", // URL of the product image
"options": [
{
"name": "<string>",
"values": ["<string>"] // Array of option values
}
],
"onlineStoreUrl": "<string>", // URL for product-level website redirection (if enabled)
"variants": [
{
"id": "<string>", // Unique identifier for the variant
"title": "<string>", // Title of the variant (e.g., size or weight)
"price": "<string>", // Price of the item
"inventoryQuantity": "<number>", // Stock left in the inventory
"inventoryPolicy": "continue | <other>", // Inventory policy
"inventoryManaged": "<boolean>", // Indicates if inventory is tracked
"image": "<string>", // URL of the variant image
"selectedOptions": [
{
"name": "<string>",
"value": "<string>" // Selected option value
}
]
}
]
}
[
{
"id": "5784365783465",
"title": "Beige Suit",
"image": "https://www.privacyguides.org",
"options": [
{
"name": "size",
"values": ["X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large"]
}
],
"onlineStoreUrl": "https://www.privacyguides.org",
"variants": [
{
"id": "58347657834647",
"title": "Beige Suit / Small",
"price": "999.00",
"inventoryQuantity": 457,
"inventoryPolicy": "continue",
"inventoryManaged": true,
"image": "https://thenewoil.org",
"selectedOptions": [
{
"name": "size",
"value": "Small"
}
]
},
{
"id": "478568734657834",
"title": "Beige Suit / Medium",
"price": "600.00",
"inventoryQuantity": 324,
"inventoryPolicy": "continue",
"inventoryManaged": true,
"image": "https://thenewoil.org",
"selectedOptions": [
{
"name": "size",
"value": "Medium"
}
]
}
]
},
{
"id": "65463457674534565",
"title": "Dark Chocolate",
"image": "https://www.privacyguides.org",
"options": [
{
"name": "weight",
"values": ["1 kg"]
}
],
"variants": [
{
"id": "58347657834647",
"title": "Dark Chocolate / 1 kg",
"price": "999.00",
"inventoryQuantity": -2345,
"inventoryPolicy": "continue",
"inventoryManaged": false,
"image": "https://thenewoil.org",
"selectedOptions": [
{
"name": "weight",
"value": "1 kg"
}
]
}
]
}
]
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
}
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Method: GET

URL: {{domain_name}}/products

  • ids product ids with comma separated values. (eg : {{domain_name}}/ products/ids=p1,p2,p3) - If passed response should only have details of the productIds sent in the parameter ids
  • if no params are passed, details of all available products has to be sent in the response
{
"id": "<string>", // Unique identifier for the product
"title": "<string>", // Title of the product
"status": "ACTIVE | <inactive>", // Status of the product
"tags": ["<string>"], // Tags associated with the product
"description": "<string>", // Description of the product
"onlineStoreUrl": "<string>", // URL for product-level website redirection (if enabled)
"image": "<string>", // URL of the product image
"options": [
{
"name": "<string>",
"values": ["<string>"] // Array of option values
}
],
"variants": [
{
"id": "<string>", // Unique identifier for the variant
"title": "<string>", // Title of the variant
"price": "<string>", // Price of the variant
"description": "<string>", // Description of the variant
"image": "<string>", // URL of the variant image
"selectedOptions": [
{
"name": "<string>",
"value": "<string>" // Selected option value
}
]
}
]
}
[
{
"id": "5784365783465",
"title": "Beige Suit",
"image": "https://www.privacyguides.org",
"status": "ACTIVE",
"description": "This is a product",
"onlineStoreUrl": "https://www.privacyguides.org",
"tags": ["BOB_1", "BOB_2"],
"options": [
{
"name": "size",
"values": ["X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large"]
}
],
"variants": [
{
"id": "58347657834647",
"title": "Beige Suit / Small",
"price": "999.00",
"description": "This is a variant",
"image": "https://thenewoil.org",
"selectedOptions": [
{
"name": "size",
"value": "Small"
}
]
},
{
"id": "58347657834577",
"title": "Beige Suit / Medium",
"price": "1999.00",
"description": "This is a variant",
"image": "https://thenewoil.org",
"selectedOptions": [
{
"name": "size",
"value": "Medium"
}
]
}
]
},
{
"id": "5784365783445",
"title": "DarkChocolate",
"image": "https://www.privacyguides.org",
"status": "ACTIVE",
"description": "This is a product",
"tags": [],
"options": [
{
"name": "weight",
"values": ["1 kg"]
}
],
"variants": [
{
"id": "6482348372",
"title": "DarkChocolate / 1 kg",
"price": "999.00",
"description": "This is a variant",
"image": "https://thenewoil.org",
"selectedOptions": [
{
"name": "weight",
"value": "1 kg"
}
]
}
]
}
]
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
}
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Method: GET

URL: {{domain_name}}/variants/:variantId

{
"id": "<string>", // Unique identifier for the variant
"title": "<string>", // Title of the variant
"price": "<string>", // Price of the item
"inventoryQuantity": "<number>", // Stock left in the inventory
"inventoryPolicy": "continue | <other>", // Inventory policy
"inventoryManaged": "<boolean>", // Indicates if inventory is tracked
"image": "<string>", // URL of the variant image
"product": {
"id": "<string>", // Unique identifier for the product
"title": "<string>", // Title of the product
"image": "<string>" // URL of the product image
}
}
{
"id": "58347657834647",
"title": "1 kg",
"price": "999.00",
"inventoryQuantity": 457,
"inventoryPolicy": "continue",
"inventoryManaged": true,
"image": "https://thenewoil.org",
"product": {
"id": "5784365783465",
"title": "Rum Chocolate",
"image": "https://www.privacyguides.org"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
}
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Method: PUT

URL: {{domain_name}}/products/:productId

{
"tags": ["tag1", "tag2", "tag3"]
}
{
"id": "6862294089884",
"title": "Nougat Chocolate", "status": "ACTIVE",
"tags": ["BOB_TAG1", "BOB_TAG2", "TAG3"]
}
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
}
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Creating an order consists of 2 steps, order creation (this will create an order with status as pending) and place order (will change the status of the order to processing and adds payment information for prepaid orders)

For COD orders both create order and place order APIs are called. For PRE- PAID orders create order API is called and when the payment is done place order API will be called with payment details.

This API should create an order (which is not actual order) with status as pending and should return orderId (whose status is pending).

NOTE: Order with pending status is not considered as an order

Method: POST

URL: {{domain_name}}/create-order

{
"customerName": "Maria",
"customerPhone": "phone number",
"customerEmail": "temp8765123@gmail.com",
"description": "anything_relevant",
"paymentType": "COD/ONLINE", // Based on payment method selected by customer
"total_amount": "923.00",
"shipping_amount": "50.00", // cart_value + tax + shipping - discount
"tax_amount": "0",
"discount_amount": "2.00",
"note": "Order drafted by BusinessOnBot",
"cart": [
{
"id": "794347765802",
"title": "Rum Chocolate",
"variant": {
"id": "39729358340272",
"title": "Default Title",
"price": "875.00",
"quantity": 1
}
}
],
"shippingAddress": {
"firstName": "Maria",
"lastName": "Hill",
"phone": "phone number",
"address1": "Test",
"address2": "test",
"city": "test",
"province": "AP",
"country": "India",
"zip": "521001"
},
"discount": {
"value": 2,
"valueType": "Amount/Percentage",
"description": "anything_relevant"
}
}
{
"OrderId": "6862294319260", // Order ID (ensure the order has status 'pending')
"status": "pending" // Will be updated to 'processing' on the place order API call
}
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
}
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Place an order (change status to processing)

Section titled “Place an order (change status to processing)”

This API will be called to change the status of the order to processing

Case 1: if its COD order no “paymentId” will be sent

Case 2: if its Prepaid order “paymentId” will be sent and it should be considered as a prepaid order

In both the cases order’s status will be processing

Method: POST

URL: {{domain_name}}/place-order

{
"OrderId": "6862294319260", // Order ID with status 'pending'
"status": "processing",
"paymentPending": true/false // Will be true if COD is selected
}
{
"id": "#1234", // Order ID with status 'processing'
"name": "#1234", // Order ID alias with status 'processing'
"status": "processing"
}
{
"status": "failure",
"statusCode": 400,
"error": "Bad Request!!"
}
{
"status": "failure",
"statusCode": 500,
"error": "Internal Server Error!!"
}

Was this page helpful?

Still stuck? Email support@businessonbot.com