[GET] Back in stock form fields

Returns the list of fields the merchant configured in their Back In Stock form (Form Builder in the app admin). Use this before calling create, so you know exactly which field ids exist, which are required, and — for choice fields — which values are valid.

Authorization: Bearer <shop_api_token>

Scopes used on this page: read_back_in_stock, write_back_in_stock.

Scope: read_back_in_stock

1. Request

GET /back-in-stock/form

No parameters.

Response — 200

{
  "success": true,
  "data": [
    {
      "id": "selectVariant",
      "label": "Select variant",
      "placeholder": "",
      "type": "selectVariant",
      "required": true,
      "hidden": false,
      "options": null,
      "defaultValue": null
    },
    {
      "id": "email",
      "label": "Email",
      "placeholder": "Enter your email address",
      "type": "email",
      "required": true,
      "hidden": false,
      "options": null,
      "defaultValue": null
    },
    {
      "id": "checkbox",
      "label": "Do you want SMS updates too?",
      "placeholder": "",
      "type": "checkbox",
      "required": false,
      "hidden": false,
      "options": ["Option 1", "Option 2"],
      "defaultValue": null
    }
  ]
}

Field object

Key	Type	Description
id	string	Unique key for the field. This is what you use as the key in content when submitting (except for the three core fields below).
label	string	Merchant-facing label configured for the field. May contain raw HTML (e.g. a field asking to accept Terms & Conditions with a link) — display as-is or sanitize on your side, it is never executed server-side.
placeholder	string	Placeholder text, if any.
type	string	One of: selectVariant, email, phone, text, textarea, select, radio, checkbox, acceptTerms, hidden. See the type reference table below.
required	boolean	Whether the merchant marked this field as required.
hidden	boolean	Whether the field is visually hidden from the customer-facing form. A hidden field can still be required — it typically means the value is meant to be supplied programmatically rather than typed by a human.
options	array of strings | null	Only present for select, radio, checkbox. The list of valid choices. null for every other type.
defaultValue	string | null	Default value configured by the merchant, if any.

Known limitation: for fields of type hidden, the merchant can configure either a fixed value or a value computed dynamically in the storefront widget from other field selections. Neither the fixed value nor the dynamic rules are currently exposed by this endpoint. If a form has a hidden field, contact us to get the value out-of-band, or omit it — it is not enforced as required by the API even if configured as such.

---

2. Submitting field values on POST /back-in-stock/create

Three field ids are core and are never part of content — they map to their own top-level request parameters instead:

Field id from GET /form	Maps to request parameter
selectVariant	product_id + variant_id
email	customer_email
phone	customer_phone

Every other field returned by GET /form (any text, textarea, select, radio, checkbox, acceptTerms, or hidden field) is submitted inside the content object, keyed by its id.

Request parameters (full list)

Parameter	Type	Required	Notes
customer_email	email	yes
product_id	number	yes
variant_id	number	yes
customer_phone	phone	no	Format: [phone]
locale	string	no	Example: en
note	string	no
content	object	no	Custom field values. See mapping table below. Any key that doesn't match a field id returned by GET /form (and isn't source or keyLabel) is silently dropped before saving.
content.keyLabel	object	no	Map of { fieldId: label } for the custom fields you're sending. Strongly recommended — without it, the merchant's admin UI and CSV exports will show the raw field id instead of a readable label.

Value format by field type

type	Where it goes	Value format
selectVariant	product_id, variant_id	numbers
email	customer_email	email string
phone	customer_phone	phone string, e.g. [phone]
text	content[id]	free-form string
textarea	content[id]	free-form string (multi-line)
select	content[id]	a single value, must exactly match one entry in the field's options
radio	content[id]	a single value, must exactly match one entry in the field's options
checkbox	content[id]	comma-separated string of selected values, e.g. "Option 1,Option 2" — each part must match one entry in options. Omit the key (or send "") if nothing is checked.
acceptTerms	content[id]	the field's configured "checked" value as a string (commonly "True") when the customer accepted; omit or send "" when not accepted
hidden	content[id]	see the known limitation above — value isn't currently discoverable via this API

Validation

• If a field is required: true (and not hidden: true), its value must be present and non-empty in content, otherwise the request fails with success: false and a message like Field "X" is required.

• For select / radio / checkbox fields, every submitted value must match one of the field's configured options, otherwise the request fails with Invalid value for field "X".

• If content is sent but is not a JSON object, the request fails with content must be an object.

• All validation failures return HTTP 200 with "success": false and a message, consistent with the rest of this API — check success, not the HTTP status code.

Example: full request

Given the form fields example under section 1 (a required checkbox field with id checkbox and options ["Option 1", "Option 2"]):

{
  "product_id": 123456789,
  "variant_id": 987654321,
  "customer_email": "[e-mail]",
  "customer_phone": "[phone]",
  "locale": "en",
  "note": "VIP customer",
  "content": {
    "checkbox": "Option 1,Option 2",
    "keyLabel": {
      "checkbox": "Do you want SMS updates too?"
    }
  }
}

Example: minimal request (no custom fields configured, or none required)

{
  "product_id": 123456789,
  "variant_id": 987654321,
  "customer_email": "[e-mail]"
}

Example: validation error response

{
  "success": false,
  "message": "Field \"Do you want SMS updates too?\" is required"
}

Example: success response

{
  "success": true,
  "message": "Submission created successfully",
  "data": {
    "id": 12345,
    "product_id": 123456789,
    "variant_id": 987654321,
    "customer_email": "[e-mail]",
    "customer_phone": "[phone]",
    "product_title": "Product Name",
    "variant_title": "Size M / Blue",
    "sku": "SKU-001",
    "inventory_id": "45678901234",
    "status": 0,
    "last_sent": null,
    "unsubscribe": 0,
    "content": "{\"checkbox\":\"Option 1,Option 2\",\"keyLabel\":\"{\\\"checkbox\\\":\\\"Do you want SMS updates too?\\\"}\",\"source\":\"api\"}",
    "locale": "en",
    "opened": 0,
    "clicked": 0,
    "note": "VIP customer",
    "created_at": "2026-08-21T10:00:00.000000Z",
    "updated_at": "2026-08-21T10:00:00.000000Z"
  }
}

Note that content in the response is a JSON-encoded string, not a nested object — decode it if you need to read individual field values back.

---

Recommended integration flow

1. Call GET /back-in-stock/form once (cache the result — it only changes when the merchant edits their form builder) to get the current field list.

2. Build your own submission form/UI from that list, excluding selectVariant, email, phone (render those as your product/variant picker, email input, phone input).

3. When the customer submits, send product_id, variant_id, customer_email, customer_phone as top-level parameters, and everything else as content, using the exact id from step 1 as the key.

4. Always include content.keyLabel mapping each custom field id to its label, so the merchant sees readable data in their admin and exports.

5. Handle success: false responses — surface the message to the customer or retry with corrected data as needed.