[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: `+9123456789`
`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. `+9123456789`
`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": "[email protected]",
  "customer_phone": "+9123456789",
  "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": "[email protected]"
}

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": "[email protected]",
    "customer_phone": "+9123456789",
    "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

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.
Build your own submission form/UI from that list, excluding selectVariant, email, phone (render those as your product/variant picker, email input, phone input).
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.
Always include content.keyLabel mapping each custom field id to its label, so the merchant sees readable data in their admin and exports.
Handle success: false responses — surface the message to the customer or retry with corrected data as needed.

Was this helpful?

Report an issue