Orders

Notify the order customer

Sends the customer of an order an email in the store name, or a fixed text message from the merchant's package.

POST/stores/{storeId}/v1/orders/{id}/notifications

Scopecustomers.notify:writeMessage order customers

An email has your own subject (3 to 160 characters) and body (up to 5,000 characters), appears in the order's message log, and is limited to 60 messages an hour per store.

A text message has fixed wording, because the sender is a registered service sender, so free text is not accepted. Choose a template: order_shipped, out_for_delivery or delivered. Each template goes once per order and is charged to the merchant's message package, and the merchant can turn any of them off.

The status of a text message is sent, already_sent (sent before and not charged again) or retrying (the store is retrying by itself, so do not send it again). The status of an email is sent, pending (the store is retrying by itself, so do not send it again) or failed (it could not be delivered and the store stopped trying). See Marketing and customer messages.

Path parameters

idstringrequired

Headers

Idempotency-Keystringrequired

Response

dataobjectrequired
order_idstring
channelstring: email sms
templatestring: order_shipped out_for_delivery delivered
statusstring: For a text message: sent, already_sent or retrying. For an email: sent, pending or failed.
executionobject: Who executed the request: the app, version, installation and store. Field names here are camelCase.
appIdstring (uuid)
versionIdstring (uuid)
installationIdstring (uuid)
storeIdstring (uuid)
requestIdstring (uuid)
generationinteger
routeEpochinteger
appAuthEpochinteger
grantRevisioninteger
metaobjectrequired
request_idstring (uuid): The request ID; include it in any support request.

Errors

HTTP	Code	Meaning
400	`IDEMPOTENCY_KEY_REQUIRED`	No Idempotency-Key header.
404	`RESOURCE_NOT_FOUND`	The ID does not exist in this store.
409	`CUSTOMER_EMAIL_MISSING`	The order has no customer email.
409	`CUSTOMER_PHONE_MISSING`	The order has no valid customer phone.
409	`SMS_NOT_ENABLED`	The merchant turned this message off, or the store has no message package.
409	`SMS_NO_BALANCE`	The merchant's message package is empty.
409	`SMS_NOT_SENT`	The message could not be sent.
409	`SHIPPING_ORDER_NOT_ELIGIBLE`	A text message for an order that is unpaid, cancelled, refunded, or has nothing to ship.
422	`INVALID_NOTIFICATION_CHANNEL`	channel is not email or sms.
422	`INVALID_NOTIFICATION_TEMPLATE`	Unknown template.
422	`INVALID_INPUT`	The email subject or body is outside its limits.
429	`MESSAGE_LIMIT_REACHED`	The store reached 60 emails this hour.
403	`SCOPE_REQUIRED`	The token does not carry the required scope.
503	`APPS_SCOPE_RUNTIME_NOT_READY`	The resource is not enabled on this merchant's store yet.

Shared codes are listed in Errors.

curl -X POST "https://larm.sa/stores/$STORE_ID/v1/orders/200123/notifications" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Idempotency-Key: $UUID" \ -H "Content-Type: application/json" \ -d '{ "channel": "sms", "template": "out_for_delivery" }'

{ "data": { "order_id": "200123", "channel": "sms", "template": "out_for_delivery", "status": "sent" }, "execution": { "appId": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9", "versionId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "installationId": "c7e4a1f2-6b3d-4e8a-9c05-1d2f3a4b5c6d", "storeId": "5b1d7a62-0c4e-4f38-9a51-2e7b3c9d8f10", "requestId": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a", "generation": 1, "routeEpoch": 4, "appAuthEpoch": 1, "grantRevision": 2 }, "meta": { "request_id": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a" } }