Skip to main content

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
In this section: