syncStore

2025-04-03 09:56

POST /v2/pos/syncStore

The syncStore API is called by the POS provider to synchronize with D-Store the information of a merchant's specific store. You can call this API in the following scenarios:

Create a new store
Change the store status to open or close an existing store

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description
requestId	String	Yes	The unique ID that is assigned by the POS provider to identify a store synchronization request. Maximum length: 255 characters Note: This field is an idempotency key field. For the syncStore requests that are initiated with the same requestId value, D-Store must return the same result. For details about API idempotency, see the Idempotency chapter.
posAccountId	String	Yes	The unique ID that is assigned by the POS provider to identify a merchant account. This identifier also marks a single digital store that can include multiple store locations. Maximum length: 64 characters
store	DetailedStoreInfo	Yes	The merchant's store information.
extendInfo	Object	No	An extended attribute that is used to provide additional information if necessary. Maximum length: 4096 characters

Response parameters

Field	Data type	Required	Description
result	Result	Yes	The result of the store synchronization request.

More information

How to handle the result

You might receive different results from D-Store. Follow the instructions in this table to handle the result.

*result.resultStatus*	*result.resultCode*	Synchronization status	Actions
`S`	`SUCCESS`	Successful	N/A
`F`	Multiple possible values exist, such as `ACCESS_DENIED`, `PROCESS_FAIL`, etc.	Failed	Take actions according to the result code (specified in the result.resultCode parameter). For more information, see Result codes.
`U`	`UNKNOWN_EXCEPTION`	Unknown	Use the same parameters to retry the syncStore request. If you keep receiving the same result indicating the unknown status, contact overseas_support@service.alibaba.com.
No result received		Unknown	Use the same parameters to retry the syncStore request. If you keep receiving no results, contact overseas_support@service.alibaba.com.

Result codes

Result code	Result status	Result message	Further action
SUCCESS	S	success	N/A
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	Contact overseas_support@service.alibaba.com to troubleshoot the issue.
PARAM_ILLEGAL	F	Parameter names or values do not meet the specified requirements. The result message can vary according to the specific error encountered.	Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of this API, see the Structure section.
INVALID_API	F	The called API is invalid or not active.	Check whether the correct API name is used when making the API call.
INVALID_SIGNATURE	F	Signature is invalid.	Check whether the public key, signed message, and signature algorithm are as expected.
ACCESS_DENIED	F	Access is denied	Contact overseas_support@service.alibaba.com to troubleshoot the issue.
REQUEST_TRAFFIC_EXCEED_LIMIT	F	The request traffic exceeds the limit.	Reduce the API calling frequency.
UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.	Recall the API.

Samples

Request

Create a new store

The following sample shows that the POS provider requests to create a new store for a merchant:

copy
{
  "requestId":"20231220bsefibb334",
  "posAccountId":"pos_account_id_001",
  "store":{
    "posStoreId":"pos_store_id_001",
    "name":"Store A",
    "status":"OPEN",
    "fullAddress":"******, Bangkok, Thailand",
    "mobileNo":"459*****67"
  }

Close a store

The following sample shows setting a universal end time for the closing period across all channels using the store.extendInfo.closingEndTimes.defaultClosingEndTime parameter:

copy
{
  "requestId":"20231220bsefibb334",
  "posAccountId":"pos_account_id_001",
  "store":{
    "posStoreId":"pos_store_id_001",
    "status":"CLOSED",
    "extendInfo":{
      "closingEndTimes":{
        "defaultClosingEndTime":"2024-01-04T00:00:00+08:00" 
      }
    }
  }

Response

The following sample shows that D-Store handles the synchronization request successfully:

copy
{
  "result": {
    "resultCode":"SUCCESS",
    "resultMessage":"success",
    "resultStatus":"S"
  }
}