> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yuko.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Points estimate

> Estimates how many loyalty points a customer will earn for a given set of cart items.

The estimate is based on your active **Place an order** earn rules. The customer is optional, so guest checkouts are supported.

<Warning>The request carries product and variant IDs only, with no prices or quantities, so the cart amount used in the calculation is always `0`. Every **Place an order** rule then falls at or below its minimum purchase, so the endpoint currently returns `0` points for every request, including fixed-points rules. Don't show this estimate to shoppers until you've confirmed it returns non-zero values for your earn rules.</Warning>

<Info>Requires the `read:points` scope. See [Scopes](/developer/api/scopes).</Info>

## Body parameters

<ParamField body="customer" type="object | null">
  The customer placing the order. Optional: omit it entirely (or send `null`) for guest checkouts. If you send a `customer` object, include at least `id` or `email`; an object with neither returns a `500` error.

  <Expandable title="customer properties">
    <ParamField body="id" type="string | null">
      The platform customer ID. Used to look up the customer if `email` is not provided.
    </ParamField>

    <ParamField body="email" type="string<email> | null">
      The customer's email address. Takes priority over `id` when both are provided; if no customer matches the email, `id` isn't tried.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="object[]" required>
  The line items in the cart. Must contain at least one item.

  <Expandable title="item properties">
    <ParamField body="product_id" type="string" required>
      The platform product ID.
    </ParamField>

    <ParamField body="variant_id" type="string" required>
      The platform variant/SKU ID.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="estimate properties">
    <ResponseField name="points_earned" type="integer">
      The estimated number of loyalty points the customer will earn after completing the purchase. Currently always `0` (see the warning above).
    </ResponseField>

    <ResponseField name="message" type="string">
      A human-readable message to display to the customer.
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | Code | When |
| :- | :- | :- |
| `401` | `missing_token`, `invalid_token` | The API key is missing, wrong or revoked. |
| `403` | `insufficient_scope` | The key doesn't have `read:points`. |
| `422` | `validation_error` | The request body is invalid, for example `items` is missing or empty. |
| `429` | | The key exceeded the [rate limit](/developer/api/rate-limits). |
| `500` | | A `customer` object was sent with neither `id` nor `email`. |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
    --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    --header "Content-Type: application/json" \
    --data '{
      "customer": {
        "id": "cus_847362",
        "email": "rahul.sharma@example.com"
      },
      "items": [
        {
          "product_id": "prod_1001",
          "variant_id": "var_1001_red_m"
        },
        {
          "product_id": "prod_2044",
          "variant_id": "var_2044_black_42"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.yukoapp.com/api/v1/public/points/estimate",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        customer: {
          id: "cus_847362",
          email: "rahul.sharma@example.com",
        },
        items: [
          {
            product_id: "prod_1001",
            variant_id: "var_1001_red_m",
          },
          {
            product_id: "prod_2044",
            variant_id: "var_2044_black_42",
          },
        ],
      }),
    }
  );

  const data = await response.json();
  ```

  ```php PHP theme={null}
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/points/estimate");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      "customer" => [
          "id"    => "cus_847362",
          "email" => "rahul.sharma@example.com",
      ],
      "items" => [
          [
              "product_id" => "prod_1001",
              "variant_id" => "var_1001_red_m",
          ],
          [
              "product_id" => "prod_2044",
              "variant_id" => "var_2044_black_42",
          ],
      ],
  ]));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "Content-Type: application/json",
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "points_earned": 0,
      "message": "You will earn 0 points after completing this purchase"
    }
  }
  ```

  ```json 422 (validation error) theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "The items field is required.",
      "details": {
        "items": ["The items field is required."]
      }
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "invalid_token",
      "message": "Invalid or revoked API token"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.