Merchant Open API

Merchants need to log in to the console to obtain the Merchant Developer Secret before calling this series of APIs.

Introduction

Request Method

HOST: https://open.idatariver.com
Headers: Authorization: Bear Your_Developer_Secret

Multi-language Support

The platform supports automatic translation of merchant project/product information into multiple languages. To obtain information in a specific language, simply include the X-Idr-Locale field in the Headers.

The translated content will be stored in the nameI18n and descI18n fields.

Currently, the automatic translation includes the name and desc fields of projects/products.

X-Idr-Locale	Language
en	🇬🇧 English
fa	🇮🇷 Persian
zh-cn	🇨🇳 Simplified Chinese
ja	🇯🇵 Japanese
ru	🇷🇺 Russian
zh-hk	🇭🇰 Traditional Chinese
de	🇩🇪 German
ar	🇦🇪 Arabic
es	🇪🇸 Spanish
fr	🇫🇷 French
ko	🇰🇷 Korean
tr	🇹🇷 Turkish
uk	🇺🇦 Ukrainian
uz	🇺🇿 Uzbek
kk	🇰🇿 Kazakh
pl	🇵🇱 Polish
pt	🇵🇹 Portuguese
pa	🇮🇳 Punjabi

Request Example

GET RequestPOST Request

shell

curl https://open.idatariver.com/mapi?key=value \
  -H "Authorization: Bearer $iDataRiver_Merchant_Secret" \
  -H "X-Idr-Locale: en" \

shell

curl https://open.idatariver.com/mapi \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $iDataRiver_Merchant_Secret" \
  -H "X-Idr-Locale: en" \
  -d '{
    "key": "value"
  }'

Response Format

To ensure uniform management and maintenance of the API, responses follow the field format below:

Field Name	Description
code	(Required) Return code, an integer representing the business status. Detailed meanings are provided in the table below.
result	(Optional) The complete raw result, with its structure and explanations provided by the supplier.
msg	(Optional) Reason for request failure.

Return Code Explanation

The meaning and explanation of the code field:

code	Description
0	Request successful
1000	Internal error
1001	Parameter error
1002	Requested resource not found
1003	Internal processing busy, please try again later
1004	Insufficient permissions

API Documentation

Use Cases

Open APIs are divided into Public APIs and Private APIs with the following differences:

Public APIs are generally triggered by users, such as placing orders, viewing product information on the merchant's homepage, etc., suitable for use in the frontend of independent sites.

Private APIs should only be used by merchants themselves to access or manage core merchant data, suitable for backend processing of merchant data management.

Even Public APIs should not be directly exposed in the frontend to avoid leaking merchant secrets.

Basic Merchant Store Information Public

Returns basic merchant information.

GET /mapi/merchant/basicInfo

Merchant Homepage Information Public

Returns a list of merchant projects along with all product information under each project.

GET /mapi/merchant/info

Get Order Details Public

Retrieve detailed information of an order by order ID.

GET /mapi/order/info

Field	Type	Required	Description
id	string	Yes	Order ID

Create Product Order Public

Place a product order.

POST /mapi/order/add

Field	Type	Required	Description
projectId	string	Yes	Project ID
skuId	string	Yes	Product ID
orderInfo	object	Yes	Order details, example: `{"quantity": 1,"coupon": "","contactInfo": "","affCode":""}`, where `quantity` is the order quantity, `coupon` is the discount coupon (if none, pass an empty string), `contactInfo` is the contact information (required), used for retrieving the order, with string length of `5-100`, and `affCode` is the affiliate promotion code (optional).

For the BUYMEABTC project, the skuId field is not required. The orderInfo field format is as follows:

{"amount":5, "private": false, "name": "", "message": ""}

amount Sponsorship amount, in USD
private Whether to make the sponsorship information public
name Nickname, can be empty
message Message, can be empty

Pay for Product Order Public

Get the order payment redirection link.

If the order price is 0, the purchase will be successful directly and no payment link will be returned.

POST /mapi/order/pay

Field	Type	Required	Description
id	string	Yes	Order ID
method	string	Yes	Payment method, from the `method` value in the `mPayments` field of the order details interface
redirectUrl	string	No	Redirection link after successful payment, should point to the order page and include the complete domain name
callbackUrl	string	No	Backend callback notification triggered when the order status changes, the order data will be sent to this link via a POST request (in JSON format), please process it within 5 seconds and return a 200 status code, otherwise it will be considered a callback failure. Current callback failures will not be retried. This URL must use a domain name and cannot be accessed through IP

Query Product Order List Public

Query the order list based on the contact information or order ID left when creating the order.

GET /mapi/order/search

Field	Type	Required	Description
query	string	Yes	Contact information or order number left when placing the order

Non-Public API

Please note, the following APIs are used to access or modify merchant internal private data and are only used for the merchant's own data management.

Get Merchant Order List Private

Retrieve the merchant's order list in reverse chronological order.

GET /mapi/order/list

Field	Type	Required	Description
status	string	No	Order status, default is empty indicating no status filtering, possible values: `DONE` (completed), `NEW` (new order), `EXPIRED` (expired), `REFUND` (refunded)
page	string	No	Pagination parameter, default is 1, increment by 1 for each page

Get All Projects Private

Returns all projects created by the merchant, including projects that are not yet online.

GET /mapi/project/list

Get Specific Project Private

Retrieve all data contained in a project, including product list, pricing list, and coupon list.

Digital products will return all inventory data.

GET /mapi/project/detail

Field	Type	Required	Description
id	string	Yes	Project ID

Create New Project Private

Create a new project.

POST /mapi/project/add

Field	Type	Required	Description
name	string	Yes	Project name
type	string	Yes	Project type, currently supports digital products: DIGITAL

Update Project Information Private

Update basic project information.

POST /mapi/project/update

Field	Type	Required	Description
id	string	Yes	Project ID, can be obtained from the project list interface
name	string	Yes	Project name, no more than 50 characters
status	string	Yes	Project status, possible values: `ONLINE`, `OFFLINE`
i18nType	string	No	Automatic translation status, possible values: enable-`0`, disable-`1`, default is `0`
desc	string	No	Project description, no more than 500 characters
cover	string	No	Image base64 encoding, no more than `2Mb`, only supports `PNG`, `JPG`, `JPEG` formats, example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAkACQAAD...`

Delete Project (Irreversible) Private

Delete a project.

POST /mapi/project/remove

Field	Type	Required	Description
project	string	Yes	Project ID

Get Single Product/SKU Details Private

Retrieve detailed information of a specific product under a project. Digital products will return data items.

POST /mapi/project/sku/detail

Field	Type	Required	Description
id	string	Yes	Product/SKU ID

Add Project Product/SKU Private

Add a product under a specified project.

POST /mapi/project/sku/add

Field	Type	Required	Description
projectId	string	Yes	Project ID

Update Product/SKU Private

Update product information.

When modifying digital product inventory data, the new data will directly overwrite the original inventory data items.

Therefore, if you need to change the inventory data items of digital products, please take the product offline first to avoid conflicts with ongoing orders.

POST /mapi/project/sku/update

Field	Type	Required	Description
id	string	Yes	Product/SKU ID
name	string	No	Product name, no more than 50 characters
status	string	No	Product status, possible values: `ONLINE`, `OFFLINE`
priority	number	No	Product priority, range is `1-100`
itemType	string	No	Data item type, possible values: reusable-`reuse`, consumable-`consumable`
items	array	No	Digital product data items, each element corresponds to a card code, example: `["123", "456"]`, must pass the `itemType` parameter simultaneously. 🔔 This value will directly overwrite the original card codes, please use cautiously
docLink	string	No	External document link
hiddenStock	bool	No	Whether to hide inventory, values `true` or `false`
desc	string	No	Project description, no more than 500 characters

When updating a product, at least one valid field needs to be updated, otherwise it will return a failure.

Delete Product/SKU Private

Permanently delete a product, cannot be undone.

POST /mapi/project/sku/remove

Field	Type	Required	Description
id	string	Yes	Product/SKU ID

Add Pricing Plan Private

Add a pricing plan.

POST /mapi/project/pricing/add

Field	Type	Required	Description
projectId	string	Yes	Project ID

Update Pricing Plan Private

Update a pricing plan.

POST /mapi/project/pricing/update

Field	Type	Required	Description
id	string	Yes	Pricing plan ID
status	string	Yes	Product status, possible values: `ONLINE`, `OFFLINE`
scope	string	Yes	Product status, possible values: global-`global`, specific range-`specific`
scopeItems	array	No	When `scope`=`specific`, this array contains the IDs of the products to be affected and cannot be empty
policy	string	Yes	Pricing strategy, possible values: fixed price-`fixed`, wholesale price-`stage_quantity`
price	string	No	Fixed price, required when `policy`=`fixed`
stages	object	No	Wholesale price settings, required when `policy`=`stage_quantity`, example: `[{ "threshold": 0, 'price': 10 },{ "threshold": 10, 'price': 8 }]` means the unit price is 10 USD for purchases less than 10 units, and 8 USD for purchases of 10 units or more, with a maximum of 5 stages

Delete Pricing Plan Private

Permanently delete a pricing plan, cannot be undone.

Please ensure that there is at least one available pricing plan for the product.

POST /mapi/project/pricing/remove

Field	Type	Required	Description
id	string	Yes	Pricing plan ID

Add Coupon Private

Add a coupon.

POST /mapi/project/coupon/add

Field	Type	Required	Description
projectId	string	Yes	Project ID

Update Coupon Private

Update coupon rules.

POST /mapi/project/coupon/update

Field	Type	Required	Description
id	string	Yes	Coupon ID
status	string	Yes	Product status, possible values: `ONLINE`, `OFFLINE`
scope	string	Yes	Product status, possible values: global-`global`, specific range-`specific`
scopeItems	array	No	When `scope`=`specific`, this array contains the IDs of the products to be affected and cannot be empty
policy	string	Yes	Pricing strategy, possible values: reduction coupon-`reduction`, discount coupon-`discount`, fixed price coupon-`fixed`
reduction	number	No	Reduction amount for reduction coupons, required when `policy`=`reduction`
fixed	number	No	Fixed price amount for fixed price coupons, required when `policy`=`fixed`
discount	number	No	Discount percentage, range `1-100`, required when `policy`=`discount`
capped	number	No	Discount cap amount, used to control the maximum discount amount when `policy`=`discount`

Delete Coupon Private

Permanently delete a coupon, cannot be undone.

POST /mapi/project/coupon/remove

Field	Type	Required	Description
id	string	Yes	Coupon ID

Telegram Bot Bulk Messaging Private

This feature requires merchants to first enable a custom Telegram bot. Merchants can also use the Telegram Bulk Messaging Assistant directly in the store.

Add a Telegram broadcast message to be sent using the merchant's custom Telegram bot.

🔔 This interface does not limit the number of bulk messages, but only one bulk message can be processed at a time. You must wait for the previous bulk message to be processed before sending another.

It is strongly recommended to use this feature wisely. Each bulk message will automatically filter out invalid users.

POST /mapi/rainbow/broadcast/add

Field	Type	Required	Description
content	string	Yes	Bulk message content, no more than 4000 characters
test	bool	Yes	Whether it is test mode, pass `true` to send only to the account bound by the merchant (commonly used for testing before official bulk messaging), pass `false` to send to all users who can receive messages

Get Telegram Bot Bulk Messaging History Private

Retrieve recent Telegram bot bulk messaging history, including total number of users, number of users who declined, number of successful sent, and total execution time.

GET /mapi/rainbow/broadcast/list

Merchant Open API ​

Introduction ​

Request Method ​

Multi-language Support ​

Request Example ​

Response Format ​

Return Code Explanation ​

API Documentation ​

Basic Merchant Store Information Public ​

Merchant Homepage Information Public ​

Get Order Details Public ​

Create Product Order Public ​

Pay for Product Order Public ​

Query Product Order List Public ​

Get Merchant Order List Private ​

Get All Projects Private ​

Get Specific Project Private ​

Create New Project Private ​

Update Project Information Private ​

Delete Project (Irreversible) Private ​

Get Single Product/SKU Details Private ​

Add Project Product/SKU Private ​

Update Product/SKU Private ​

Delete Product/SKU Private ​

Add Pricing Plan Private ​

Update Pricing Plan Private ​

Delete Pricing Plan Private ​

Add Coupon Private ​

Update Coupon Private ​

Delete Coupon Private ​

Telegram Bot Bulk Messaging Private ​

Get Telegram Bot Bulk Messaging History Private ​