Back in stock headless
When running Shopify as headless, back-in-stock functionality is achieved using this endpoint:
POST https://live.voyado.eastsideapps.io/api/back-in-stock/subscribe
The payload sent to this endpoint to define a subscription for a particular item looks like this:
{ "shop": "store-uk.myshopify.com", "locale": "en", "country": "GB", "preSelectStatus": false, "email": "john@example.com", "acceptsEmail": true, "acceptsSms": false, "hasPhone": false, "phone": "+4671234567", "variant": { "id": "47695659598128", "is_available": false, "sku": "jersey-XS-red" }, "product": { "id": "8386707489072" } }
The output to Engage will then look like this for the contact creation request:
{ "language": "en", "countryCode": "GB", "email": "john@example.com", "acceptsEmail": true, "acceptsSms": false, "mobilePhone": "+4671234567", }
And like this for the create subscription request:
{ "ContactId": "f5774867-1234-445f-85a4-af1200eced95", "Locale": "en-GB", "Sku": "jersey-XS-red", "ExternalId": "store-uk.myshopify.com" }
Field definitions
Field name | Type | Description |
---|---|---|
shop* | string | The shop's unique identifier on Shopify Example: "store-uk.myshopify.com" |
locale* | string | The locale setting of the merchant Example: "en" |
country* | string | The country code of the users location Example: "GB" |
preSelectStatus* | boolean | If marketing opt-in is preselected. Example: false |
email* | string | The email address of the user. Must be a valid email format. Example: john@example.com". |
acceptsEmail* | boolean | Indicates whether the user accepts Email communication Example: true |
acceptsSms | boolean | Indicates whether the user accepts SMS communication Example: false |
hasPhone | boolean | Indicates whether the user has provided a phone number. Example: false |
variant.id* | string | The variant's unique identifier. Example: "47695659598128" |
variant.sku* | string | The stock-keeping-unit associated with the variant. Example: "jersey-XS-red" |
variant.is_available* | boolean | Indicates whether the variant is available for purchase. Example: false |
product.id | string | The product's unique identifier Example: "8386707489072" |
Fields marked with (*) are mandatory.
More about preSelectStatus
The preSelectStatus field indicates whether the marketing opt-in checkbox is pre-selected on the back-in-stock subscription form. This boolean value is set by the merchant and determines the initial state of the marketing opt-in option for users interacting with the widget.
true: The marketing opt-in checkbox is now pre-selected, meaning customers will be opted into marketing communications by default unless they choose to opt out.
false: In this case the marketing opt-in checkbox is not pre-selected, meaning customers will need to actively opt into marketing communications.
The preSelectStatus is used to determine if an update to a customer's preferences is necessary. It ensures that any updates do not override consent previously given by the customer.
Data flow
Here is the data flow when working with back-in-stock subscriptions:
![back-in-stock-02.png](../../../image/166dafc219fccc.png)