Idempotency

2023-04-28 21:00

If a request timeout error occurs when you call an API, you might attempt to resend the request. In this case, you can configure the specified idempotent fields in the request to help avoid unwanted duplication in case of failures and retries.

An API call is idempotent if it has the same result no matter how many times the API call is applied. For example, idempotency can guarantee that the payment is charged only once if the same API payment call is retried multiple times in the case of a timeout error. You can retry the request via using the same idempotent field to guarantee that no more than one charge is created.

Idempotent fields

The following table lists the idempotent fields of specific OpenAPIs.

API name	Idempotent field	Rule
/v2/miniprogram/qrcode/create	appId, appQrCodePage, appQrCodePage, and appQrCodeParams	These four fields are idempotent fields when they are used at the same time. For the QR code generated with the same appId, appQrCodePage, appQrCodePage, and appQrCodeParams and reach an S status, the same QR code value and image will be returned.
/v2/miniprogram/message/send	requestId	This field is an API idempotent field. For the notifications which are sent with the same requestId and reach an S status, the super app must return the same messageId.
syncBenefit	benefitSyncRequestId	This field is an API idempotent field. For benefit synchronization requests which are initiated with the same benefitSyncRequestId, our server must return the same result.
issueBenefit	benefitIssueRequestId	This field is an API idempotent field. For the benefit issuing requests which are initiated with the same benefitIssueRequestId, ISVs must return the same result.
reverseBenefitIssue	benefitIssueRequestId	This field is an API idempotent field. For the requests to reverse the benefit issuing which are initiated with the same benefitIssueRequestId, ISVs must return the same result.
syncUsedBenefit	benefitUseRequestId	This field is an API idempotent field. For synchronization requests of used benefits which are initiated with the same benefitUseRequestId, our server must return the same result.
initializeShoppingArea	requestId	This field is an API idempotent field. For the initializeShoppingArea requests using the same requestId value, our server must return the same result.
initializeBrand	requestId	This field is an API idempotent field. For the initializeBrand requests using the same requestId value, our server must return the same result.
initializeStore	requestId	This field is an API idempotent field. For the initializeStore requests using the same requestId value, our server must return the same result.
createOrder	requestId	This field is an API idempotent field. For the createOrder requests that are initiated with the same requestId value, the SaaS provider or ISV must return the same result.
notifyOrderAcceptance	requestId	This field is an API idempotent field. For the notifyOrderAcceptance requests that are initiated with the same requestId value, our server must return the same result.
notifyOrderCompletion	requestId	This field is an API idempotent field. For the notifyOrderCompletion requests that are initiated with the same requestId value, our server must return the same result.
notifyOrderChange	requestId	This field is an API idempotent field. For the notifyOrderChange requests that are initiated with the same requestId value, our server must return the same result.
addShoppingArea	requestId	This field is an idempotent field. For the addShoppingArea requests using the same requestId value, our server must return the same result.
addBrand	requestId	This field is an idempotent field. For the addBrand requests using the same requestId value, our server must return the same result.
addStore	requestId	This field is an idempotent field. For the addStore requests using the same requestId value, our server must return the same result.
addMenu	requestId	This field is an idempotent field. For the addMenu requests using the same requestId value, our server must return the same result.
addCategory	requestId	This field is an idempotent field. For the addCategory requests using the same requestId value, our server must return the same result.
addItem	requestId	This field is an API idempotent field. For the addItem requests using the same requestId value, our sever must return the same result.
addModifierGroup	requestId	This field is an API idempotent field. For the addModifierGroup requests using the same requestId value, our server must return the same result.
notifyCardRegistration	requestId	This field is an API idempotent field. For the notifyCardRegistration requests using the same requestId value, the merchant must return the same result.
issueCard	requestId	This field is an API idempotent field. For the issueCard requests using the same requestId value, Mini Program Platform must return the same result.
topup	requestOrderId	This field is an API idempotent field. For the topup requests using the same requestOrderId value, the merchant must return the same result.
syncStore	requestId	This field is an API idempotent field. For the syncStore requests using the same requestId value, D-store Platform must return the same result.