API Documentation for BayEngage (2.0.0)

Download OpenAPI specification:Download

This is a documentation that covers all of BayEngage's Custom APIs

Authentication

Use this API to generate an access token, essential for authenticating and authorizing requests. Log in to BayEngage with your credentials. Navigate to the "App" section, then select "Custom Integration" "Settings". Ensure that the version is set to 2.0. Generate the Client ID and Client Secret Key for API integration. Ensure that the bearer token obtained is used for authorization in all APIs.

Generate Access Token

Obtain an access token using client credentials.

Request Body schema: application/x-www-form-urlencoded
client_id
required
string

INSERT_YOUR_CLIENT_ID_HERE

client_secret
required
string

INSERT_YOUR_CLIENT_SECRET_HERE.

grant_type
required
string

client_credentials

scope
required
string

Provide necessary scope Eg. read_campaign write_campaign

Responses

Response samples

Content type
application/json
{
  • "access_token": "ACCESS TOKEN",
  • "expires_in": 3599,
  • "scope": "read_campaign write_campaign",
  • "token_type": "bearer"
}

Tenant

API for managing tenant tag details.

Get Tenant Information

Fetching the details of the tenant, including their subscription, settings, and other metadata.

Authorization: This endpoint requires a bearer token with the read_tenant scope.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get All Tenant Tags

Fetches a list of all available Tenant tags.

Authorization : This endpoint requires an bearer token with the read_account scope

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Templates

APIS for managing Email/SMS templates.

Create a new Email template

This endpoint allows you to save a new email template.

Authorization : This endpoint requires an bearer token with the write_email_template scope

Authorizations:
bearerAuth
Request Body schema: application/json

Request body to create a new template.

source
required
string

The source of the template creation (e.g., 'api').

title
required
string

The title of the template.

content
required
string

The HTML content of the template.

Responses

Request samples

Content type
application/json
{
  • "source": "api",
  • "title": "store offer template",
  • "content": "<html> </html>"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Send Test Email

Send a test email to the provided customer email's using a given template ID or custom HTML content. You must provide either a template_id or html content. If both are missing, a 422 error is returned.

Authorization : This endpoint requires a bearer token with the write_email_template scope.

Authorizations:
bearerAuth
Request Body schema: application/json
preview_customer_id
string

Insert your preview customer ID

html
required
string

HTML content or template_id is mandatory

template_id
string

HTML content or template_id is mandatory

subject
string

Subject of your test email template

preview
string

Preview text of your test email template

emails
required
Array of strings <email>

Insert your email ID

from_name
string

From name of your test email

from_email
string

From email of your test email

Responses

Request samples

Content type
application/json
{
  • "preview_customer_id": "726876742",
  • "html": "<p>Hello, this is a your custom html.</p>",
  • "template_id": "4112",
  • "subject": "Save your Money: 3 for $99.99 or 5 for $159.99",
  • "preview": "LIMITED STOCK! Shop fast to avial it while supplies last.",
  • "emails": [
    ],
  • "from_name": "John Doe",
  • "from_email": "john.doe@targetbay.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get Single Email Template.

Retrieves details of a specific email template.

Authorization : This endpoint requires an bearer token with the read_email_template scope

Authorizations:
bearerAuth
path Parameters
template_id
required
integer

The unique identifier of the template.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get All Email Templates.

Fetches a list of available templates with their metadata and associated campaigns.

Authorization : This endpoint requires a bearer token with the read_email_template scope

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Labour day sale

Search templates by title

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

sort_by
string
Enum: "created_at:desc" "created_at:asc" "id:desc" "id:asc"
Example: sort_by=id:desc

Sorting parameter.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get All SMS Templates.

Retrieves a list of SMS templates.

Authorization: This endpoint requires a bearer token with the read_sms_template scope

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Offer sale

Title search.

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer
Example: limit=10

Number of records per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Contacts

APIs for managing customer contacts in BayEngage.

Create and Update an Email contact in BayEngage

Contact details can be included along with the Email contact. A new contact will be created for the provided email. If contact already exists, contact details will be updated.

Authorization : This endpoint requires a bearer token with the write_customer scope

Authorizations:
bearerAuth
Request Body schema: application/json

Request body to create a new contact.

required
integer or string

Unique ID of the customer in your platform.

email
required
string

This is the email address of the customer. Either email or phone is mandatory.

phone
string

This is the phone number of the customer.

source
required
string
Default: "api"

This is an identification for source of contact creation. The source is mandatory to create the contact.

email_subscription
required
string

Possible values are "active", "unsub", "not_subscribed" This is the subscription status of your customer. The contact is added as subscribed or unsubscribed based on this value.

phone_optin_trigger
boolean
Enum: true false

Indicates whether to trigger an SMS opt-in message to the provided phone number. Set to true to send opt-in message; false to skip.

phone_optin_trigger will not work by default, reach support@targetbay.com for activation.

phone_subscription
string

Possible values are "unverified", "unsub"

phone_subscription will not work by default, reach support@targetbay.com for activation.

phone_existing_subscription
string

Possible values is "retain". By using this key user account phone status will not override.

Learn more. https://help.targetbay.com/s/article/Understanding-the-phone-existing-subscription-Field-in-the-Create-Contact-API

tags
Array of strings

Customer tags for grouping purposes

custom_fields
Array of objects

Custom attributes for the customer with key-value pairs

first_name
string

This is the customer's first name

last_name
string

This is the customer's last name

address1
string

The customer's primary street address

address2
string

The customer's secondary street address (apartment, suite, etc.)

city
string

The customer's city

province
string

The customer's state or province

zip
string

The customer's postal or zip code

country
string

The customer's country

list_id
string

This is the list UUID where your contact have been added to in BayEngage. You can find the List UUID is the list settings page. If this UUID misspelled or not provided your contact will be added into website contact default list.

Responses

Request samples

Content type
application/json
{
  • "platform_customer_id": 984112,
  • "email": "johndoe@targetbay.com",
  • "phone": "+1xxxxxxxxxx",
  • "source": "api",
  • "email_subscription": "active",
  • "phone_optin_trigger": false,
  • "phone_subscription": "unverified",
  • "phone_existing_subscription": "retain",
  • "tags": [
    ],
  • "custom_fields": [
    ],
  • "first_name": "John",
  • "last_name": "Doe",
  • "address1": "Melrose Avenue",
  • "address2": "102",
  • "city": "Los Angeles",
  • "province": "Michigan",
  • "zip": "30303",
  • "country": "United States",
  • "list_id": "58133f44864d"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Fetch all email contacts in BayEngage

The API that should be used to fetch all contacts in BayEngage.

Authorization : This endpoint requires a bearer token with the read_customers scope

Authorizations:
bearerAuth
query Parameters
email
string <email>
Example: email=john.dew@targetbay.com

Filter by customer email address.

phone
integer
Example: phone=9147866311

Filter by customer phone number.

fields[address]
string
Example: fields[address]=*

Fetch customer address information. Use * to fetch all address fields, or specify specific fields: type, customer_id, address_street_1, address_street_2, city, state, country, country_code, zip_code.

fields[tags]
string
Example: fields[tags]=*

Fetch customer tags. Use * to fetch all tag fields, or specify specific fields: name, linkable_id, linkable_type.

fields[lists]
string
Example: fields[lists]=*

Fetch customer list subscriptions. Use * to fetch all lists.

fields[custom_fields]
string
Example: fields[custom_fields]=*

Fetch custom field values for customers. Use * to fetch all custom fields.

filter_by[email]
string <email>
Example: filter_by[email]=john.dew@targetbay.com

Filter by customer email address. Only one filter can be used at a time.

filter_by[phone]
string
Example: filter_by[phone]=9147866311

Filter by customer phone number. Only one filter can be used at a time.

filter_by[platform_customer_id]
string
Example: filter_by[platform_customer_id]=2334

Filter by platform customer ID. Only one filter can be used at a time.

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer [ 1 .. 100 ]
Default: 25

The number of items to return per page. The default value is 25 items and the maximum is 100 per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Batch create email contacts in BayEngage

Create multiple contacts in a single request.

Authorization : This endpoint requires a bearer token with the write_customer scope

Authorizations:
bearerAuth
Request Body schema: application/json

Request body to create multiple contacts.

Array of objects

The array that contains the list of subscribers

Responses

Request samples

Content type
application/json
{
  • "subscribers": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Delete an Email contact in BayEngage

Delete an Email contact in BayEngage.

Authorization : This endpoint requires a bearer token with the write_customer scope

Authorizations:
bearerAuth
path Parameters
required
integer or string

The customer ID that you wish to delete, use platform customer id to perform delete operation.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Category

This API Allows users to create, update, and delete category in BayEngage.

Get Categories

Fetches a list of categories with pagination.

Authorization : This endpoint requires an bearer token with the read_category scope

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Hoodies

Category search, will works only based on categories handle.

page
integer
Example: page=1

Page number for pagination

limit
integer
Example: limit=10

Number of records per page

sort_by
string
Enum: "id:asc" "id:desc"
Example: sort_by=id:desc

Sort category by id (ascending or descending).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Create or Update Category

Create or update a category..

Authorization : This endpoint requires an bearer token with the write_category scope

Authorizations:
bearerAuth
Request Body schema: application/json
required
integer or string

Unique identifier for the category. Can be an integer or a string.

parent_id
number

Identifier of the parent category.

name
required
string

Name of the category.

code
required
string

Code for the category Eg - shirts-men.

Responses

Request samples

Content type
application/json
{
  • "platform_category_id": "2545aa",
  • "parent_id": 1,
  • "name": "shirts-men",
  • "code": "shirts-men"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "data": {
    }
}

Delete Category

Deletes a category identified by its platform_category_id.

Authorization : This endpoint requires an bearer token with the write_category scope

Authorizations:
bearerAuth
path Parameters
required
integer or string

The platform_category_id of the category to delete. Can be passed as a string or an integer.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Product

This API helps manage products by allowing users to add, update, and delete products, as well as fetch a list of existing products.

Get a list of products.

Fetch products based on various filters such as type, date range, and stock availability.

Authorization : This endpoint requires an bearer token with the read_product scope

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

type
string
Enum: "title" "product" "sku" "recently_added_products" "most_purchased_products" "most_viewed_products"
Example: type=most_purchased_products

Type of products to filter.

search
string
Examples:
  • search=Nike Shoes - Search by product title
  • search=123456 - Search by platform product ID

Search for products by title, platform product ID.

stock_filter
string
Enum: "all" "in_stock" "out_of_stock"
Example: stock_filter=all

Filter products by stock availability.

product_id
integer
Example: product_id=214318

Fetch details of a specific product from bayengage.

category_id
integer
Example: category_id=4112

Fetch details of a specific category id from bayengage.

integer or string

Fetch details of a specific platform product.

integer or string

Fetch details of a specific platform category id.

custom_attribute1
Array of strings
Example: custom_attribute1=Basketball

Sport associated with the products. e.g sport=[Basketball, Golf]

custom_attribute2
Array of strings
Example: custom_attribute2=NBA

league associated with the products. e.g league=[NBA, NCAA]

price[less_than]
number
Example: price[less_than]=500

Filter products with price less than the specified value.

price[greater_than]
number
Example: price[greater_than]=100

Filter products with price greater than the specified value.

price[equals]
number
Example: price[equals]=250

Filter products with price equals to the specified value.

price[between]
string
Example: price[between]=300,700 or price[between]=[300,700]

Filter products with price between two values (comma-separated or array).

review_date_range
string
Enum: "today" "yesterday" "7days" "30days" "90days" "lastmonth" "custom"

The time range for filtering products by review date.

review_start_date
string
Example: review_start_date=28-09-2024 15:20:30

Start date and time in dd-mm-yyyy H:i:s format (e.g., 28-09-2024 15:20:30). Required if review_date_range is "custom".

review_end_date
string
Example: review_end_date=28-09-2024 22:20:30

End date and time in dd-mm-yyyy H:i:s format (e.g., 28-09-2024 22:20:30). Required if review_date_range is "custom".

sort_by
string
Enum: "review_rating:asc" "review_rating:desc"
Example: sort_by=review_rating:desc

Sort products by review rating (ascending or descending).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Create or Update Product

Create or update a product. This endpoint accepts a payload containing product details.

Authorization : This endpoint requires an bearer token with the write_product scope

Authorizations:
bearerAuth
Request Body schema: application/json
required
integer or string

Unique identifier for the product. Can be passed as a string or an integer.

product_title
required
string

Title of the product.

description
string

Product description.

vendor
string

Vendor or brand of the product.

product_type
required
string

Type of the product (e.g., simple or variant).

product_url
string

URL of the product.

product_status
string

Status of the product (e.g., "1" for active and "0" for inactive).

Array of objects

List of product categories.

tags
string

Comma-separated product tags.

required
Array of objects

List of product variants.

Array of objects

List of product images.

custom
object

Custom attributes for the product.

Responses

Request samples

Content type
application/json
{
  • "platform_product_id": "44422aa",
  • "product_title": "Iphone 16 1TB",
  • "description": "Iphone 16 1TB comes with many colour option, More offers on credit card purchase",
  • "vendor": "Apple",
  • "product_type": "simple",
  • "product_status": "1",
  • "product_category": [
    ],
  • "tags": "electronics,phone,iphone",
  • "variants": [
    ],
  • "images": [],
  • "custom": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "data": {
    }
}

Delete Product

Delete a product by its platform_product_id.

Authorization : This endpoint requires an bearer token with the write_product scope

Authorizations:
bearerAuth
path Parameters
required
integer or string

The platform_product_id of the product to delete. This value can be passed either as a string or an integer.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Product deleted successfully"
}

Order

This API enables users to create, update, and delete orders in BayEngage.

Create and Update Order

Create or update an order.

Authorization : This endpoint requires an bearer token with the write_order scope

Authorizations:
bearerAuth
Request Body schema: application/json
required
integer or string

Unique identifier for the order on the platform. This value can be passed either as a string or an integer.

email
required
string

Customer's email address.

cart_token
required
string

Cart token associated with the order Eg - '83d188b46c3396d880c20c187f56e679'

phone
number

Customer's phone number Eg - '8990998999'.

created_at
required
string <date-time>

Order creation timestamp. (format - YYYY-MM-DD HH:MM:SS).

completed_at
string <date-time>

Order completion timestamp. (format - YYYY-MM-DD HH:MM:SS).

currency
string

Currency code Eg - 'USD'

current_subtotal_price
required
number

Subtotal price of the order.

current_total_discounts
number

Total discounts applied.

current_total_price
required
number

Total price of the order.

current_total_tax
number

Total tax for the order.

Array of objects

List of discount codes applied.

refunds
object or null

Refund details if any.

status
required
string
Enum: "open" "closed" "cancelled"

Order status.

financial_status
string
Enum: "authorized" "pending" "paid" "partially_paid" "refunded" "voided" "partially_refunded" "unpaid" "expired"

Financial status of the order.

fulfillment_status
string
Enum: "shipped" "partial" "unshipped" "unfulfilled" "pending" "fulfilled"

Fulfillment status of the order.

fulfilled_at
string <date-time>

Order fulfillment timestamp. (format - YYYY-MM-DD HH:MM:SS).

integer or string

Order number can be 1004112 or 'TGB004112'

required
Array of objects

Billing address details.

required
Array of objects

List of order items.

required
Array of objects

Shipping address details.

Responses

Request samples

Content type
application/json
{
  • "platform_order_id": "4112bb",
  • "email": "user_mail_id@domain.com",
  • "cart_token": "83d188b46c3396d880c20c187f56e679",
  • "phone": 8990998999,
  • "created_at": "2021-08-04T15:13:40.000Z",
  • "completed_at": "2022-02-02T13:25:20.000Z",
  • "currency": "USD",
  • "current_subtotal_price": 950,
  • "current_total_discounts": 0,
  • "current_total_price": 950,
  • "current_total_tax": 0,
  • "discount_codes": [
    ],
  • "refunds": null,
  • "status": "open",
  • "financial_status": "paid",
  • "fulfillment_status": "pending",
  • "fulfilled_at": "2022-02-06T13:25:20.000Z",
  • "order_number": 5674898,
  • "billing_address": [
    ],
  • "line_items": [
    ],
  • "shipping_address": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "data": {
    }
}

Delete Order

Deletes an order by its platform_id. Pass the platform_order_id as a path parameter.

Authorization : This endpoint requires an bearer token with the write_order scope

Authorizations:
bearerAuth
path Parameters
required
integer or string

The unique platform_order_id of the order to delete. This value can be passed either as a string or an integer.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Order deleted successfully"
}

Get Orders List

Fetch orders with optional date range and platform order ID filtering, with pagination support.

Authorization : This endpoint requires a bearer token with the read_order scope

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number for pagination.

limit
integer >= 1
Default: 25
Example: limit=50

Number of records per page.

filter_by[date_range]
string
Enum: "today" "yesterday" "7days" "30days" "90days" "lastmonth" "custom"
Example: filter_by[date_range]=7days

Filter orders by predefined or custom date ranges.

filter_by[start_date]
string <date>
Example: filter_by[start_date]=01-01-2024

Start date for custom date range filtering. Required when date_range=custom. Format dd-mm-yyyy.

filter_by[end_date]
string <date>
Example: filter_by[end_date]=31-01-2024

End date for custom date range filtering. Required when date_range=custom. Format dd-mm-yyyy.

filter_by[platform_order_id]
string
Example: filter_by[platform_order_id]=ORDER12345

Filter by specific platform order ID. Must be a single ID (no comma-separated values).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Review

This API allows users to fetch product reviews/ QnAs and manage moderation and admin reply for both.

Get Product review list

Fetch all the product reviews with optional date range , search by title,content, consumer name, filter by rating, product id, status; sorting based on newest, oldest, highest_rating, lowest_rating., with pagination support.

Authorization : This endpoint requires a bearer token with the read_review scope

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number for pagination.

limit
integer >= 1
Default: 10
Example: limit=50

Number of records per page.

filter_by[status]
string
Enum: "published" "pending" "unpublished" "spam" "trash"
Example: filter_by[status]=unpublished

Filter product reviews by moderation status.

filter_by[date_range]
string
Enum: "today" "yesterday" "7days" "30days" "90days" "lastmonth" "custom"
Example: filter_by[date_range]=7days

Filter orders by predefined or custom date ranges.

filter_by[start_date]
string <date>
Example: filter_by[start_date]=01-01-2024

Start date for custom date range filtering. Required when date_range=custom. Format dd-mm-yyyy.

filter_by[end_date]
string <date>
Example: filter_by[end_date]=31-01-2024

End date for custom date range filtering. Required when date_range=custom. Format dd-mm-yyyy.

filter_by[platform_product_id]
string
Example: filter_by[platform_product_id]=1001

Filter by specific product ID. Must be a single ID (no comma-separated values).

filter_by[rating]
integer
Example: filter_by[rating]=3

Filter by specific review rating. Values ranges from 1 to 5. Must be single (no comma-separated values).

search
string
Example: search=Good product

Free text that searches in title or content or customer name or customer email.

sort_by
string
Enum: "newest" "oldest" "highest_rating" "lowest_rating"
Example: sort_by=highest_rating

Sort the review order. Allowed values are newest, oldest, highest_rating, lowest_rating.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get a specific product review

Fetch a specific product review with all the details.

Authorization : This endpoint requires a bearer token with the read_review scope

Authorizations:
bearerAuth
path Parameters
review_id
required
string
Example: 507f1f77bcf86cd799439011

Review ID of the product review to be fetched.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Moderate a specific product review

Perform one of the 2 actions on a specific review, add admin comment and/or update moderation status.

Authorization : This endpoint requires a bearer token with the write_review scope

Authorizations:
bearerAuth
path Parameters
review_id
required
string
Example: 507f1f77bcf86cd799439011

Review ID of the product review to be fetched.

Request Body schema: application/json
reply
string

Admin reply given to acknowledge the review posted by customer

is_reply_private
boolean

When true, the reply given is not eligible to be shown in public widget

status
string
Enum: "published" "unpublished" "spam" "trash"

The moderation status. Required when reply is not provided. Allowed values are published, unpublished, trash.

reason
integer
Enum: "1 (Unrelated to the Product or Service)" "2 (Inappropriate/Profanity)" "3 (Legal transgression)" "4 (Other Languages/ Unsupported Languages)" "5 (Contains Confidential information)" "6 (False or misleading)" "7 (Fake)" "8 (Low rating)" "9 (Previously approved review)" "10 (Review containing more than one link)" "11 (Reviews have email address)"

The numeric code for unpublishing reason. Required when status is 'unpublished'

Responses

Request samples

Content type
application/json
{
  • "reply": "Thank you for your valuable feedback, we will ensure to maintain the same quality!",
  • "is_reply_private": false,
  • "status": "unpublished",
  • "reason": 3
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get Product question list

Fetch all the product questions with optional date range , search by question, consumer name or email, filter by product id, status, date; sorting based on newest, oldest., with pagination support.

Authorization : This endpoint requires a bearer token with the read_review scope

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

Page number for pagination.

limit
integer >= 1
Default: 10
Example: limit=50

Number of records per page.

filter_by[status]
string
Enum: "published" "unpublished" "trash"
Example: filter_by[status]=unpublished

Filter product questions by moderation status.

filter_by[date_range]
string
Enum: "today" "yesterday" "7days" "30days" "90days" "lastmonth" "custom"
Example: filter_by[date_range]=7days

Filter orders by predefined or custom date ranges.

filter_by[start_date]
string <date>
Example: filter_by[start_date]=01-01-2024

Start date for custom date range filtering. Required when date_range=custom. Format dd-mm-yyyy.

filter_by[end_date]
string <date>
Example: filter_by[end_date]=31-01-2024

End date for custom date range filtering. Required when date_range=custom. Format dd-mm-yyyy.

filter_by[platform_product_id]
string
Example: filter_by[platform_product_id]=1001

Filter by specific product ID. Must be a single ID (no comma-separated values).

search
string
Example: search=How much is shipping?

Free text that searches in question content or customer first/last name or customer email

sort_by
string
Example: sort_by=newest

Sort the product question order. Allowed values: newest, oldest

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get a specific product question and answer details

Fetch a specific product question with all the details.

Authorization : This endpoint requires a bearer token with the read_review scope

Authorizations:
bearerAuth
path Parameters
question_id
required
string
Example: 507f1f77bcf86cd799439011

Question ID of the product question to be fetched.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Moderate a specific product question

Perform one of the 2 actions on a specific question, add admin answers(upto 3 answers allowed) and/or update moderation status.

Authorization : This endpoint requires a bearer token with the write_review scope

Authorizations:
bearerAuth
path Parameters
question_id
required
string
Example: 507f1f77bcf86cd799439011

Question ID of the product question to be fetched.

Request Body schema: application/json
answer
string

Admin answer given to question posted by customer

is_answer_private
boolean

When true, the answer given is not eligible to be shown in public widget

status
string
Enum: "published" "unpublished" "spam" "trash"

The moderation status. Required when answer is not provided. Allowed values are published, unpublished, trash.

Responses

Request samples

Content type
application/json
{
  • "answer": "Thank you for your valuable feedback, we will ensure to maintain the same quality!",
  • "is_answer_private": false,
  • "status": "unpublished"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Product question moderated successfully",
  • "locale": "en",
  • "data": {
    }
}

Cart

This API allows users to create, update cart data within BayEngage.

Create and Update Cart in BayEngage

Tracks user cart details including platform token, email, and items for tracking and follow-ups.

Authorization : This endpoint requires an bearer token with the write_cart scope

Authorizations:
bearerAuth
Request Body schema: application/json
platform_cart_token
required
string

Token identifying the cart from the platform.

email
string <email>

Email address of the customer.

Array of objects non-empty

Array of product items in the cart.

created_at
string <date-time>

Timestamp when the cart was created.

Responses

Request samples

Content type
application/json
{
  • "platform_cart_token": "83d188b46c3396d880c20c187f56e6",
  • "email": "your_mail_id@domain.com",
  • "line_items": [
    ],
  • "created_at": "2024-03-28T13:28:28.939Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Checkout

This API allows users to create, update, and manage checkout sessions within BayEngage.

Create and Update Checkout in BayEngage

Checkout details like items, customer info, shipping, and marketing consent to support abandoned cart recovery and conversion tracking.

Authorization : This endpoint requires an bearer token with the write_checkout scope

Authorizations:
bearerAuth
Request Body schema: application/json
platform_checkout_id
required
integer

Unique ID of the checkout process in your platform.

token
required
string

Unique token identifying the session or user.

status
required
string
Value: "process"

Current status of the checkout process. Allowed value:process.

email
required
string

Email address of the customer.

buyer_accepts_email_marketing
required
boolean

Indicates if the buyer consents to receive email marketing.

currency
required
string

Currency code in "USD".

required
Array of objects

List of items included in the checkout.

abandoned_checkout_url
required
string

URL that allows the customer to return and complete the checkout.

buyer_accepts_sms_marketing
required
boolean

Indicates if the buyer consents to receive SMS marketing.

sms_marketing_phone
required
string

Phone number provided for SMS marketing.

total_price
required
string

Total price for the checkout.

total_tax
required
string

Total tax amount for the checkout.

subtotal_price
required
string

Subtotal price before taxes and discounts.

required
object

Shipping address details.

required
object

Customer details.

Responses

Request samples

Content type
application/json
{
  • "platform_checkout_id": 694476275,
  • "token": "zumhf537g07q7fa38zuhfuahuf",
  • "status": "process",
  • "email": "your_mail_id@domain.com",
  • "buyer_accepts_email_marketing": true,
  • "currency": "USD",
  • "line_items": [
    ],
  • "buyer_accepts_sms_marketing": true,
  • "sms_marketing_phone": "9147866655",
  • "total_price": "349.99",
  • "total_tax": "15",
  • "subtotal_price": "364.99",
  • "shipping_address": {
    },
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

List & Segments

API for managing contact lists and segments. These endpoints enable users to organize, filter, and target their audience effectively.

Create a List

Creates a new list with the given title.

Authorization: This endpoint requires an bearer token with the write_list_segment scope

Authorizations:
bearerAuth
Request Body schema: application/json
title
required
string

The title of the list to be created.

Responses

Request samples

Content type
application/json
{
  • "title": "holidaylist"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Add Contacts to a List

Add one or more contacts to a list using their customer IDs.

Authorization: This endpoint requires an bearer token with the write_list_segment scope

Authorizations:
bearerAuth
Request Body schema: application/json
list_uuid
required
string

UUID of the list to which contacts will be added.

required
Array of integers or strings <= 1000 items

Array of platform customer identifiers to add to the list. Each identifier may be an integer or a string. Maximum 1000 items allowed.

Responses

Request samples

Content type
application/json
{
  • "list_uuid": "58c963f83389",
  • "platform_customer_id": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Remove Contacts from a List

Remove one or more contacts from a list using their customer IDs.

Authorization: This endpoint requires an bearer token with the write_list_segment scope

Authorizations:
bearerAuth
Request Body schema: application/json
list_uuid
required
string

UUID of the list from which contacts will be removed.

required
Array of integers or strings <= 1000 items

Array of platform customer identifiers to remove from the list. Each identifier may be an integer or a string. Maximum 1000 items allowed.

Responses

Request samples

Content type
application/json
{
  • "list_uuid": "58c963f83389",
  • "platform_customer_id": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Get All Lists & Segments

Fetches a list of all available lists and segments, with an optional search query.

Authorization : This endpoint requires an bearer token with the read_list_segment scope

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=Summer Campaign

Title search.

type
string
Enum: "all" "list" "segment"
Example: type=all

Filter by type. Options - all, list, segment.

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Campaign Management

APIs for managing Email/SMS campaigns. This includes creating, updating, scheduling, pausing, cloning, and sending campaigns.

Get Single Email/SMS Campaign

This endpoint retrieves details of a specific Email / SMS campaign by its ID.

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer
Example: 5125

The unique identifier for the campaign.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Get a list of Email/SMS campaigns.

Fetches a paginated list of Email/SMS campaigns with sorting, filtering, and status options.

Authorization : This endpoint requires an bearer token with the read_campaign scope

Authorizations:
bearerAuth
query Parameters
channel
required
string
Enum: "email" "sms"
Example: channel=email

The campaign channel (email or SMS).

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items per page.

sort_by
string
Enum: "created_at:asc" "created_at:desc"

Sort campaigns by created_at (ascending or descending).

created_at[before]
string <date>
Example: created_at[before]=26-03-2025

Filter campaigns created before the given date.

created_at[after]
string <date>
Example: created_at[after]=26-03-2025

Filter campaigns created after the given date.

scheduled_at[before]
string <date>
Example: scheduled_at[before]=26-03-2025

Filter campaigns scheduled before the given date.

scheduled_at[after]
string <date>
Example: scheduled_at[after]=26-03-2025

Filter campaigns scheduled after the given date.

published_at[before]
string <date>
Example: published_at[before]=26-03-2025

Filter campaigns published before the given date.

published_at[after]
string <date>
Example: published_at[after]=26-03-2025

Filter campaigns published after the given date.

status[]
Array of strings
Items Enum: "done" "draft" "scheduled" "published" "paused" "sending" "cancelled" "all"

Filter campaigns by status.

fields[lists]
string
Enum: "id" "title" "created_at" "updated_at"
Example: fields[lists]=title

(Optional) Select specific fields for lists.

fields[segments]
string
Enum: "id" "title" "created_at" "updated_at"
Example: fields[segments]=title

(Optional) Select specific fields for segments.

fields[template]
string
Enum: "id" "title" "created_at" "updated_at"
Example: fields[template]=title

(Optional) Select specific fields for templates.

fields[listsExclude]
string
Enum: "id" "title" "created_at" "updated_at"
Example: fields[listsExclude]=title

(Optional) Exclude specific fields from lists.

fields[segmentsExclude]
string
Enum: "id" "title" "created_at" "updated_at"
Example: fields[segmentsExclude]=title

(Optional) Exclude specific fields from segments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Create a new Email campaign.

This endpoint allows you to create a new email campaign.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
Request Body schema: application/json
title
required
string

The title of the campaign.

type
required
string
Enum: "regular" "ab_test"

The type of the campaign. Options are "regular" or "ab_test".

Responses

Request samples

Content type
application/json
{
  • "title": "summer sale offer campaign",
  • "type": "regular"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Create a new SMS Campaign

This endpoint allows you to create a new SMS campaign.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
Request Body schema: application/json
title
required
string

Campaign title.

type
required
string
Value: "sms_regular"

Campaign type (must be 'sms_regular').

Responses

Request samples

Content type
application/json
{
  • "title": "Product promotion offer campaign",
  • "type": "sms_regular"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Update a Email Campaign

Updates the details of an existing Email campaign, including recipients, delivery control, UTM tracking, and variants.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer
Example: 5146
Request Body schema: application/json
title
required
string
type
required
string
Enum: "regular" "ab_test"
required
object

Either send_to->lists->include or send_to_segments->include is required. To send to all subscribers, include 0 in lists->include.

object
required
object
object
required
Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "title": "summer sale offer campaign",
  • "type": "regular",
  • "send_to": {
    },
  • "delivery_control": {
    },
  • "utm_tracking": {
    },
  • "recipient_name": {
    },
  • "variants": [
    ],
  • "follow_ups": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Update a SMS Campaign

Updates the details of an existing SMS campaign.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer
Example: 5125

The unique identifier for the SMS campaign to update.

Request Body schema: application/json
id
required
integer

The campaign ID.

title
required
string

The title of the SMS campaign.

type
required
string

The type of campaign.

object

Delivery control settings

required
object

Either send_to->lists->include or send_to_segments->include is required. To send to all subscribers, include 0 in lists->include.

required
object

SMS UTM tracking configuration

required
Array of objects

List of SMS campaign variants.

Responses

Request samples

Content type
application/json
{
  • "id": 145985,
  • "title": "July 2026 SMS Campaign",
  • "type": "sms_regular",
  • "delivery_control": {
    },
  • "send_to": {
    },
  • "sms_utm_tracking": {
    },
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Send a Email Campaign

Schedules an email campaign for delivery.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer
Example: 5145

Unique identifier of the campaign to be sent

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Send a SMS Campaign

Schedules an SMS campaign for delivery.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer
Example: 5145

Unique identifier for the SMS campaign.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Schedule a Email/SMS Campaign.

Schedules an Email/SMS campaign for a specific campaign using the provided scheduling details.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer
Example: 5167

The unique identifier for the email campaign.

Request Body schema: application/json
timezone
required
string

The timezone in which the campaign should be scheduled.

schedule_at
required
string

The date and time when the campaign should be scheduled (format - YYYY-MM-DD HH:MM AM/PM).

send_type
required
string

The sending type for the campaign. Eg - later.

Responses

Request samples

Content type
application/json
{
  • "timezone": "America/New_York",
  • "schedule_at": "2025-02-17 06:00 PM",
  • "send_type": "later"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Pause a Email Campaign

Pauses an active email campaign.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer

The unique identifier of the campaign to be paused.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Clone a Email/SMS Campaign.

Creates a duplicate of an existing email/SMS campaign with a new title.

Authorization : This endpoint requires an bearer token with the write_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer

The unique identifier of the campaign to be cloned.

Request Body schema: application/json
title
required
string

The title of the cloned campaign.

Responses

Request samples

Content type
application/json
{
  • "title": "champion offer updated promo code"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Campaign Performance

This API provides detailed insights into the activity information of a specific email campaign and SMS campaign , offering a comprehensive view of its performance and engagement metrics.

Campaign Email Performance - Single

The API provides performance statistics for a specific email campaign.

Authorization : This endpoint requires an bearer token with the read_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer

The unique identifier for the email campaign.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Campaign SMS Performance - Single

The API provides performance statistics for a specific SMS campaign.

Authorization : This endpoint requires an bearer token with the read_campaign scope

Authorizations:
bearerAuth
path Parameters
campaign_id
required
integer

The unique identifier for SMS campaign.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Campaign Email Activity - Single

The API that should be used to fetch activity details for a specific email campaign

Authorization : This endpoint requires an bearer token with the read_campaign scope

Authorizations:
bearerAuth
query Parameters
campaign_id
required
integer

The unique identifier for email campaign.

type[]
required
Array of strings
Items Enum: "opened" "delivered" "clicked" "unsubscribed" "complained" "bounced" "all"

The type of activity to retrieve.

variant_id
required
integer
Example: variant_id=15701

The ID of the variant (Mandatory for A/B campaigns).

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

search_type
integer
Default: 1

Pass any one (1- email, 2- first name, 3- last name).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Campaign SMS Activity - Single

The API that should be used to fetch activity details for a specific SMS campaign.

Authorization : This endpoint requires an bearer token with the read_campaign scope

Authorizations:
bearerAuth
query Parameters
campaign_id
required
integer
Example: campaign_id=4112

The unique identifier for SMS campaign.

type[]
required
Array of strings
Items Enum: "delivered" "sent" "clicked" "failed" "all"

The type of activity to retrieve.

limit
integer <= 100
Default: 10

The number of items to return per page.

search
string
Example: search=+1914786xxxx

Search using mobile number

page
integer >= 1
Default: 1

The page number for pagination.

Responses

Response samples

Content type
application/json
{}

Campaign Email/SMS Performance - List

The API that should be used to fetch performance data for email/SMS campaigns.

Authorization : This endpoint requires an bearer token with the read_campaign scope

Authorizations:
bearerAuth
query Parameters
date_range
required
string
Enum: "today" "yesterday" "7days" "30days" "90days" "lastmonth" "custom"

The time range for campaign performance.

type[]
required
Array of strings
Items Enum: "regular" "ab_test" "sms_regular" "all"

The type of campaign (e.g. "regular","ab_test","sms_regular","all").

start_date
required
string
Example: start_date=28-09-2024

Start date in dd-mm-yyyy format. Required if date_range is "custom".

end_date
required
string
Example: end_date=28-09-2024

End date in dd-mm-yyyy format. Required if date_range is "custom".

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Automations Performance

This API offers in-depth activity details for specific automations, providing a comprehensive overview of their performance and engagement data.

Retrieve Flow List

Fetches a list of automation flows based on various filters.

Authorization : This endpoint requires an bearer token with the read_automation scope

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

sort_by
string
Default: "created_at:desc"
Enum: "created_at:asc" "created_at:desc" "id:asc" "id:desc" "title:asc" "title:desc"

Sort results based on creation date, ID, or title.

status[]
string
Default: "all"
Enum: "all" "published" "draft" "offline"

Filter flows based on status.

fields[event]
string
Example: fields[event]=title

Optional fields to include in the response.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Flow Performance - Single

The API to retrieve performance data for automation flows

Authorization : This endpoint requires an bearer token with the read_automation scope

Authorizations:
bearerAuth
query Parameters
flow_id
required
integer

The unique identifier for the flow.

date_range
required
string
Enum: "today" "yesterday" "7days" "30days" "90days" "lastmonth" "custom"

The time range for the flow performance.

start_date
required
string
Example: start_date=28-09-2024

Start date in dd-mm-yyyy format. Required if date_range is "custom".

end_date
required
string
Example: end_date=28-09-2024

End date in dd-mm-yyyy format. Required if date_range is "custom".

page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 10

The number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Flow Action Activity - Single

The API to retrieve detailed activities for automation flows.

Authorization : This endpoint requires an bearer token with the read_automation scope

Authorizations:
bearerAuth
path Parameters
flow_action_id
required
integer

The unique identifier for the flow action.

query Parameters
type[]
required
Array of strings
Items Enum: "all" "clicked" "opened" "delivered" "failed"

The type of activities to retrieve (e.g. "all", "clicked", "opened").

channel
required
string

The channel through which the activity occurred (e.g. sms or email).

date_range
required
string
Enum: "7days" "30days" "90days" "custom"

The time range to filter activities (e.g., "7days").

start_date
required
string
Example: start_date=28-09-2024

Start date in dd-mm-yyyy format. Required if date_range is "custom".

end_date
required
string
Example: end_date=28-09-2024

End date in dd-mm-yyyy format. Required if date_range is "custom".

page
integer >= 1
Default: 1

The page number for pagination (default is 1).

limit
integer <= 100
Default: 10

The number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}

Activity

This API allows users to create custom activities within BayEngage. Activities can be used to track user actions and trigger automations.

Create Activity

Create a custom activity in BayEngage. Activities can be used to track user actions and trigger automations based on specific events.

Authorization : This endpoint requires an bearer token with the write_automation scope.

Authorizations:
bearerAuth
Request Body schema: application/json
activity_name
required
string

The name of the activity that you wish to create.

object

User properties can contain both System fields and Custom fields. System fields are readily available within BayEngage and the data types of such fields are predefined. Custom fields are customizable and can be used for the purpose of storing additional information about the user. The data type of such custom properties can be defined by the sender using the field_type object.

object

Any additional data related to the activity can be included in the activity_properties object. This data can be made use in the email templates. The fields provided are part of the sample data related to the sample activity. The sender has to replace the sample fields with the actual fields as per the requirement.

Responses

Request samples

Content type
application/json
{
  • "activity_name": "Book rental",
  • "user_properties": {
    },
  • "activity_properties": {}
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "locale": "en",
  • "message": "OK",
  • "data": {
    }
}