
<SdkPage group="stock" />

<Method id="subscribe" signature="subbly.stock.subscribe(payload)">

Asks Subbly to email the customer when a product or a survey answer is back in
stock. Watch for `stockCount: 0` on a variant, a plan or an answer, and offer
the alert there.

The shop must turn alerts on: `shop.settings.outOfStockEnabled` and
`shop.limits.outOfStock` must both be `true`.

<Params>
  <Param name="payload" required type="StockSubscriptionPayload">
    What to watch, and where to send the alert.
    <Properties label="payload">
      <Param name="email" required type="string">
        Address the alert goes to.
      </Param>

      <Param name="productId" conditional type="number">
        The variant or plan that ran out. Send this or `answerId`, not both.
      </Param>

      <Param name="answerId" conditional type="number">
        The survey answer that ran out. Send this or `productId`, not both.
      </Param>

      <Param name="quantity" optional type="number">
        How many units the customer wants.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<StockSubscriptionResponse>">
The alert record.
<Properties>
  <Param name="id" type="number">
    ID of the record.
  </Param>

  <Param name="shopId" type="number">
    The shop the record belongs to.
  </Param>

  <Param name="productId" type="number">
    The product being watched.
  </Param>

  <Param name="email" type="string">
    Address the alert goes to.
  </Param>

  <Param name="quantity" type="number">
    How many units the customer wants.
  </Param>

  <Param name="entityId" type="number">
    ID of the watched product or survey answer.
  </Param>

  <Param name="entityType" type="'product' | 'survey_answer'">
    What is being watched.
  </Param>

  <Param name="inStockAt" type="string">
    When the item came back in stock. Empty until it does.
  </Param>

  <Param name="createdAt" type="string">
    When the record was created.
  </Param>

  <Param name="updatedAt" type="string">
    When the record last changed.
  </Param>
</Properties>
</Returns>

<Example>

```js title="Watch a variant"
await subbly.stock.subscribe({
  email: 'me@example.com',
  productId: 456,
  quantity: 1
})
```

```js title="Watch a survey answer"
await subbly.stock.subscribe({
  email: 'me@example.com',
  answerId: 789
})
```

</Example>

</Method>
