Commerce flow API
COMMERCE FLOW API, custom store API, catalog API, create order APIUse 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.
Endpoints
Section titled “Endpoints”| 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) |
Authentication
Section titled “Authentication”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’.
Responses
Section titled “Responses”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 |
Catalog
Section titled “Catalog”Get all categories
Section titled “Get all categories”Method: GET
URL: {{domain_name}}/categories
Response type
Section titled “Response type”{id: <string> (unique identifier for the category),title: <string> (title of the category)}Success response
Section titled “Success response”[ { "id": "6862294089884", "title": "Chocolates" }, { "id": "6862294349884", "title": "Cakes" } ]Error responses
Section titled “Error responses”{ "status": "failure", "statusCode": 400, "error": "Bad Request!!" }, { "status": "failure", "statusCode": 500, "error": "Internal Server Error!!" }Get products by category ID
Section titled “Get products by category ID”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.
Response type
Section titled “Response type”{ "id": "<string>", "title": "<string>", "status": "ACTIVE | <inactive>", "tags": ["<string>"]}Success response
Section titled “Success response”[ { "id": "6862294089884", "title": "Chocolates" }, { "id": "6862294349884", "title": "Cakes" } ]Error responses
Section titled “Error responses”[ { "id": "6862294089884", "title": "Chocolates" }, { "id": "6862294349884", "title": "Cakes" } ]Get a product’s variants by product ID
Section titled “Get a product’s variants by product ID”Method: GET
URL: {{domain_name}}/products/:productId
Product details type
Section titled “Product details type”{ "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 } ] } ]}Success response
Section titled “Success response”[ { "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" } ] } ] }]Error responses
Section titled “Error responses”{ "status": "failure", "statusCode": 400, "error": "Bad Request!!"}{ "status": "failure", "statusCode": 500, "error": "Internal Server Error!!"}Get all products and variants
Section titled “Get all products and variants”Method: GET
URL: {{domain_name}}/products
Query parameters
Section titled “Query parameters”- 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
Details type
Section titled “Details type”{ "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 } ] } ]}Success response
Section titled “Success response”[ { "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" } ] } ] }]Error responses
Section titled “Error responses”{ "status": "failure", "statusCode": 400, "error": "Bad Request!!"}{ "status": "failure", "statusCode": 500, "error": "Internal Server Error!!"}Get a variant by variant ID
Section titled “Get a variant by variant ID”Method: GET
URL: {{domain_name}}/variants/:variantId
Variant details type
Section titled “Variant details type”{ "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 }}Success response
Section titled “Success response”{ "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" }}Error responses
Section titled “Error responses”{ "status": "failure", "statusCode": 400, "error": "Bad Request!!"}{ "status": "failure", "statusCode": 500, "error": "Internal Server Error!!"}Update the tags of a product
Section titled “Update the tags of a product”Method: PUT
URL: {{domain_name}}/products/:productId
Request body (JSON)
Section titled “Request body (JSON)”{ "tags": ["tag1", "tag2", "tag3"]}Success response
Section titled “Success response”{ "id": "6862294089884", "title": "Nougat Chocolate", "status": "ACTIVE", "tags": ["BOB_TAG1", "BOB_TAG2", "TAG3"]}Error responses
Section titled “Error responses”{ "status": "failure", "statusCode": 400, "error": "Bad Request!!"}{ "status": "failure", "statusCode": 500, "error": "Internal Server Error!!"}Orders
Section titled “Orders”Create a draft order
Section titled “Create a draft order”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
Request body (JSON)
Section titled “Request body (JSON)”{ "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" }}Success response
Section titled “Success response”{ "OrderId": "6862294319260", // Order ID (ensure the order has status 'pending') "status": "pending" // Will be updated to 'processing' on the place order API call}Error responses
Section titled “Error responses”{ "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
Request body (JSON)
Section titled “Request body (JSON)”{ "OrderId": "6862294319260", // Order ID with status 'pending' "status": "processing", "paymentPending": true/false // Will be true if COD is selected}Success response
Section titled “Success response”{ "id": "#1234", // Order ID with status 'processing' "name": "#1234", // Order ID alias with status 'processing' "status": "processing"}Error responses
Section titled “Error responses”{ "status": "failure", "statusCode": 400, "error": "Bad Request!!"}{ "status": "failure", "statusCode": 500, "error": "Internal Server Error!!"}Was this page helpful?
Thanks, this helps us improve this page.
Still stuck? Email support@businessonbot.com