Data dictionary

Message

Field

Data type

Required

Description

Example

messageId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a notification.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

"000ALIPW3HK166730755726440330622"

customerId

String

Yes

Indicates the unique ID assigned by the super app to identify a user.

Maximum length: 32 characters

"216022004226"

messageChannel

String

Yes

Indicates the channel to send a notification.

Valid values are:

  • SMS: Send an SMS notification.
  • PUSH: Send a push notification.
  • INBOX: Send an inbox notification.

"SMS"

templateCode

String

No

Indicates the unique code assigned by the super app to identify a template.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

"HK_PDS_NOTIFY"

messageContent

String 

Yes

Indicates the specific content of a notification.

Maximum length: 4096 characters

Note:

  • This parameter supports multiple languages. The super app must make sure the message content is displayed in the user's preferred language.
  • This parameter is in JSON format containing an object. The standard parameters passed to the object can vary depending on the message channel, as follows:
    • When the value of messageChannel is PUSH, the standard parameters include:
      • title: The message title.
      • content: The message content.
      • linkUrl: The message URL.
    • When the value of messageChannel is SMS, the standard parameters include:
      • content: The message content.
    • When the value of messageChannel is INBOX, the standard parameters include:
      • header.appIcon: The icon URL of the mini program.
      • header.appName: The mini program name.
      • header.target.path: The destination URL.
      • body.title: The message title.
      • body.content: The message content.
      • body.target.path: The message URL.
      • footer.linkName: The text of the footer URL.
      • footer.target.path: The footer URL.
  • Contact our technical support if the super app has specific requirements for parameters or parameter length.

See the sample requests:

extendInfo

String 

Yes

Indicates the extended information.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?

Note: The platformTemplateCode parameter is passed in to indicate the unique code assigned by Mini Program Platform to identify a template.

{

"platformTemplateCode": "2022081611151188061000930176"

}

Result

Property

Data type

Required

Description

Example

resultStatus

String

Yes

Indicates the result status. Valid values are:

  • S: Successful
  • F: Failed
  • U: Unknown
  • A: Accepted, not yet succeeded, but can proceed with some actions.

"S"

resultCode

String

No

Indicates the result code.

  • Maximum length: 64 characters.

-

resultMessage

String

No

Indicates the result messages that describe the result code in detail.

  • Maximum length: 256 characters.

-

MessageSendResult

Field

Data type

Required

Description

Example

messageId

String 

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a notification.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

"000ALIPW3HK166730755727530328230"

success

Boolean

Yes

Indicates whether the super app successfully receives a notification.

Valid values are:

  • true: The super app successfully receives the notification.
  • false: The super app fails to receive the notification.

true

retry

Boolean

No

Indicates whether the super app allows Mini Program Platform to retry when the super app fails to receive a notification.

Valid values are: 

  • true: The super app server allows Mini Program Platform to retry in specific scenarios, such as system exceptions.
  • false: The super app server does not allow Mini Program Platform to retry. For example, when the delivery frequency of a notification exceeds the limits set by the super app, retry is not allowed.

Note: This field must be returned when the value of success is false.

false

Amount

Field

Data type

Required

Description

currency

String 

Yes

Indicates the 3-character currency code that follows ISO-4217. For example, SGD, USD, or CNY.

  • Maximum length: 3 characters

"USD"

value

Integer

Yes

Indicates the value of the amount which is in the currency's smallest unit. For example, 10000 means 100.00 in USD.

  • Value range: 0-2147483647

10000

Order

Field

Data type

Required

Description

referenceOrderId

String

Yes

Indicates the unique ID assigned by the merchant to identify a merchant's order.

  • Maximum length: 64 characters.

orderDescription

String

Yes

Indicates the description of the order.

  • Maximum length: 256 characters.

orderAmount

Amount

Yes

Indicates the total amount of an order.

orderCreateTime

Datetime

No

Indicates the date and time when an order is created. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

merchant

Merchant

Yes

Indicates the information related to the merchant.

goods

Array<Goods>

No

Indicates the information related to goods.

shipping

Shipping

No

Indicates the shipping information

buyer

Buyer

No

Indicates the buyer's information

env

Env

No

Indicates the Information about the environment where the order is placed, such as the device information.

extendInfo

String 

No

Indicates extended information. This field includes information that is not common but needed for special usage.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?

Merchant

Field

Data type

Required

Description

referenceMerchantId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a merchant.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

merchantMCC

String

No

Indicates the merchant's MCC (merchant category code). The value follows the ISO 18245 standard format.

  • Maximum length: 32 characters
  • Minimum length: 1 character

merchantName

String

Yes

Indicates the name of the merchant.

Maximum length: 256 characters

merchantDisplayName

String

No

Indicates the display name of the merchant.

  • Maximum length: 64 characters

merchantAddress

Address

No

Indicates the address of the merchant.

merchantRegisterDate

Datetime

No

Indicates the date and time when the merchant registered their business. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

merchantStore

MerchantStore

No

Indicates the information of the merchant's store.

MerchantStore

Field

Data type

Required

Description

referenceStoreId

String

Yes

Indicates the unique ID assigned by a merchant to identify a store.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

storeName

String

No

Indicates the name of the store.

  • Maximum length: 256 characters

storeMCC

String

No

Indicates the store's MCC (merchant category code). The value follows the ISO 18245 standard format.

  • Maximum length: 32 characters
  • Minimum length: 1 character

storeDisplayName

String

No

Indicates the display name of the store.

  • Maximum length: 64 characters

storeTerminalId

String

No

Indicates the unique identifier of the store's terminal.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

storeOperatorId

String

No

Indicates the unique identifier of the store's terminal operator.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

storeAddress

Address

No

Indicates the address of the store.

storePhoneNo

String

No

Indicates the contact number of the store.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

Goods

Field

Data type

Required

Description

referenceGoodsId

String

Yes

Indicates a unique ID assigned by the merchant to identify goods in the order.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

goodsName

String

Yes

Indicates the name of goods.

Maximum length: 256 characters

goodsCategory

String

No

Indicates the category of goods.

  • Maximum length: 256 characters
  • Characters not allowed: special characters such as @ # ?

goodsBrand

String

No

Indicates the brand of goods.

  • Maximum length: 32 characters

goodsUnitAmount

Amount

No

Indicates the unit amount of goods.

goodsPaymentAmount

Amount

Yes

Indicates the payment amount of goods.

goodsQuantity

Integer

No

Indicates the number of goods.

Value range: 1-unlimited

goodsSkuName

String

No

Indicates the SKU name of goods.

  • Maximum length: 64 characters

goodsUrl

String

No

Indicates the URL of goods in the mini program.

Maximum length: 2048 characters

extendInfo

String

No

Indicates the extended information about goods.

  • Maximum length: 2048 characters
  • Characters not allowed: special characters such as @ # ?

Shipping

Field

Data type

Required

Description

shippingName

UserName

Yes

Indicates the shipping name.

shippingAddress

Address

Yes

Indicates the shipping address.

shippingCarrier

String 

No

Indicates the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.

Maximum length: 128 characters

shippingPhoneNo

String 

No

Indicates the phone number of the recipient (including extension).

Maximum length: 16 characters

shippingFee

Amount

No

Indicates the shipping fee.

Buyer

Field

Data type

Required

Description

referenceBuyerId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a buyer.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

buyerName

UserName

No

Indicates the name of the buyer.

buyerPhoneNo

String

No

Indicates the contact number of the buyer.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

buyerEmail

String

No

Indicates the email address of the buyer.

Maximum length: 128 characters

Env

Field

Data type

Required

Description

terminalType

String

No

Indicates the terminal type of this request. Valid values are:

  • MINI_APP: Mini program
  • APP: Mobile application
  • WEB: Broswer website
  • WAP: Mobile WAP
  • SYSTEM: System call

osType

String

No

Indicates the operating system. Valid values are:

  • IOS: The IOS system
  • ANDROID: The Android system

userAgent

String 

No

Indicates the user's agent.

Maximum length: 1024 characters.

deviceTokenId

String 

No

Indicates the token ID of the device.

Maximum length: 128 characters.

clientIp

String 

No

Indicates the IP address of the client device.

Maximum length: 64 characters.

cookieId

String 

No

Indicates the user's cookie ID.

Maximum length: 128 characters.

storeTerminalId

String 

No

Indicates the store terminal ID.

Maximum length: 64 characters.

storeTerminal

RequestTime

Datetime

No

Indicates the store terminal request time.

Maximum length: 32 characters.

extendInfo

String 

No

Indicates extended information. This field includes information that is not common but needed for special usage.

  • Maximum length: 4096 characters.
  • Characters not allowed: special characters such as @ # ?

UserName

Field

Data type

Required

Description

fullName

String 

No

Indicates the user's full name.

Maximum length: 128 characters

firstName

String 

No

Indicates the user's first name.

Maximum length: 32 characters

middleName

String 

No

Indicates the user's middle name.

Maximum length: 32 characters

lastName

String 

No

Indicates the user's last name.

Maximum length: 32 characters

Address

Field

Data type

Required

Description

region

String

Yes

Indicates the Alpha-2 code that refers to a region according to ISO 3166, for example, JP or US.

Maximum length: 2 characters

state

String

No

Indicates State, County, or Province.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

city

String

No

Indicates City, District, Suburb, Town, or Village.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

address1

String

No

Indicates address line 1 (including Street address, P.O. box, or Company name).

  • Maximum length: 256 characters
  • Characters not allowed: special characters such as @ # ?

address2

String

No

Indicates address line 2 (including Apartment, Suite, Unit, or Building).

  • Maximum length: 256 characters
  • Characters not allowed: special characters such as @ # ?

label

String

No

Indicates the label for the address, for example, home or work.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

zipCode

String

No

Indicates the ZIP or postcode.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

longitude

String

No

Indicates the longitude of the address.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

Note: If latitude is provided, then longitude must be provided.

latitude

String

No

Indicates the latitude of the address.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

Note: If longitude is provided, then latitude must be provided.

extendInfo

String

No

Indicates the extended information of the address.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?

PaymentMethod

Field

Data type

Required

Description

paymentMethodType

String 

Yes

Indicates the payment method. Valid values are:

  • BALANCE: Deduct the amount from the balance.
  • COUPON : Redeem coupons.
  • CREDIT_CARD: Reduct the amount from a credit card.
  • DEBIT_CARD: Reduct the amount from a debit card.

paymentMethodId

String 

No

Indicates the unique ID generated by the super app to identify a payment method.

  • Maximum length: 128 characters.

paymentMethodMetaData

String 

No

Indicates the payment method metadata.

  • Maximum length: 2048 characters.

DeviceInfo

Field

Data type

Required

Description

Example

clientVersion

String

No

Indicates the version of a super app.

"1.0.0"

manufacturer

String

No

Indicates the manufacturer of a client device.

"Apple"

tokenId

String

No

Indicates the unique ID to identify a super app on the client device.

-

clientIp

String

No

Indicates the IP address of the client device.

-

osType

String

No

Indicates the operating system.

Valid values are:

  • ANDROID: The Android system
  • IOS: The iOS system

"ANDROID"

osVersion

String

No

Indicates the version of the operating system.

-

DeployAppInfo

Field

Data type

Required

Description

Example

appId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a mini program.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?

Note: The merchant obtains this parameter value by calling the my.getAppIdSync JSAPI or from Mini Program Platform.

"2102010113769***"

appName

String

Yes

Indicates the name of a mini program.

  • Maximum length: 36 characters

-

appDescription

String

Yes

Indicates the description of a mini program.

  • Maximum length: 36 characters

-

appSlogan

String

Yes

Indicates the tagline of a mini program.

  • Maximum length: 36 characters

-

deployVersion

String

Yes

Indicates the release version of a mini program, with a timestamp.

"1.0.1.1653969582308"

developerVersion

String

Yes

Indicates the release version of a mini program, without a timestamp.

"1.0.1"

iconUrl

String

Yes

Indicates the logo icon URL of a mini program.

-

categoryDetails

Array<Category>

Yes

Indicates the list of the mini program categories.

-

releaseStatus

String

Yes

Indicates the release status of a mini program.

Valid values:

  • GRAY: The mini program is in grayscale release.
  • ONLINE: The mini program is released to the super app and runs online.

"ONLINE"

createTime

String

Yes

Indicates the date and time when a mini program is created, in the timestamp format.

"1653969581000"

publishTime

String

Yes

Indicates the date and time when a mini program is released, in the timestamp format.

"1653969582000"

relatedEnv

String

Yes

Indicates the related environment where a mini program is released.

Valid values are:

  • prod: The mini program is released to the production environment.
  • dev: The mini program is released to the development environment.
  • test: The mini program is released to the test environment.
  • sandbox: The mini program is released to the sandbox environment.

"prod"

relatedClientId

String

Yes

Indicates the ID of the super app where a mini program is released.

-

relatedWorkspaceId

String

Yes

Indicates the ID of the workspace where a mini program is released.

-

packageSize

Integer

Yes

Indicates the mini program package size.

-

searchKeywords

Array<String>

No

Indicates the list of search keywords for a mini program.

This parameter is returned when the matching mini program is configured with keywords, otherwise, an empty array is returned.

  • Maximum size: 50 elements
  • Element maximum length: 50 characters

-

serviceTel

String

No

Indicates the customer service hotline of a mini program.

This parameter is returned when the matching mini program is configured with a customer service contact number.

  • Maximum length: 12 characters
  • Characters not allowed: special characters such as @ # ?

"+355-232342344"

serviceEmail

String

No

Indicates the customer service email of a mini program.

This parameter is returned when the matching mini program is configured with a customer service contact email.

"test@163.com"

Category

Field

Data type

Required

Description

Example

categoryId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a mini program category.

"1000"

categoryName

String

Yes

Indicates the name of a mini program category.

"Others"

User

Field

Data type

Required

Description

userId

String 

Yes

Indicates the unique ID assigned by the super app to identify a user.

Maximum length: 64 characters

status

String 

No

Indicates the user status.

Valid values are:

  • ACTIVE: The user account is active.
  • FROZEN: The user account is frozen.
  • INACTIVE: The user account is inactive.

nickName

String 

No

Indicates the user's nickname.

Maximum length: 256 characters

userName

UserName

No

Indicates the username.

Note: When you return this parameter, be sure to return the fullName parameter or at least one of the firstName, middleName, lastname parameters.

userAddresses

Array<Address>

No

Indicates the user's address information.

avatar

String 

No

Indicates the avatar URL.

Maximum length: 512 characters

gender

String 

No

Indicates the user's gender.

Valid values are:

  • F: Female
  • M: Male

birthDate

Datetime

No

Indicates the birth date which follows the ISO 8601 standard format (with time zone). For example, "2022-06-01T12:01:01+08:00".

nationality

String 

No

Indicates the nationality, in alpha-2 code according to ISO 3166, such as JP, US.

Maximum length: 2 characters

loginIdInfos

Array<LoginIdInfo>

No

Indicates a list of user login IDs.

contactInfos

Array<ContactInfo>

No

Indicates a list of contact information.

extendInfo

String

No

Indicates the extended information.

Maximum length: 4096 characters

LoginIdInfo

Field

Data type

Required

Description

loginIdType

String 

Yes

Indicates the type of login ID.

Valid values are:

  • MOBILE_PHONE: The login ID is a phone number.
  • EMAIL: The login ID is an email address.
  • OTHER: Other.

loginId

String 

No

Indicates a unique identifier for a user's login ID, which can be a mobile number or an email address. Users can use their login ID without hidden bits to log in to the super app.

Maximum length: 64 characters

maskLoginId

String 

No

Indicates a mask login ID that represents several bits of the phone number hidden to protect users' privacy.

Maximum length: 64 characters

hashLoginId

String 

No

Indicates a hash login ID that identifies a loginId that is hashed by a hash algorithm. The external system can use it to compare their login ID that is hashed by the same hash algorithm to check whether the login IDs are identical.

Maximum length: 256 characters

extendInfo

String 

No

Indicates the extended information.

Maximum length: 4096 characters

ContactInfo

Field

Data type

Required

Description

contactType

String 

Yes

Indicates the contact type.

Valid values are:

  • MOBILE_PHONE: Mobile phone
  • TELEPHONE: Telephone
  • EMAIL: Email

Note: Developers can add new types, but should consider the compatibility.

contactNo

String 

Yes

Indicates the value of the contactType parameter. For example, this parameter value can be a mobile phone number or an email address.

  • Maximum length: 64 characters

Note: When the value of contactType is MOBILE_PHONE, this parameter follows the [+][country code][area code without leading 0][local phone number] format, for example, +6512345678.

extendInfo

String 

No

Indicates the extended information.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?

ContentTemplate

Property

Data type

Required

Description

templateParameters

Map<String,String>

No

A string-to-string mapping. The data structure is in JSON format: 

"templateParameters": {"key": "value"}  

, where: 

  • key : represents the placeholder that is designed in the selected message template.
  • value : is used to replace the value of the  key parameter in the message template.

language

String

No

RFC 1766, such as zh-CN, en-US.