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

# Coupons

> Apply coupon codes and calculate discounts for embed checkout.

Validate a coupon code against a specific product and quantity, and get the calculated discount amount.

## Apply Coupon

<Note>
  This is a public endpoint. It requires the `X-Embed-Key` header but no customer authentication.
</Note>

```
POST /api/embed/apply-coupon
```

### Headers

| Header         | Required | Description                   |
| -------------- | -------- | ----------------------------- |
| `X-Embed-Key`  | Yes      | Your store's embed public key |
| `Content-Type` | Yes      | `application/json`            |

### Request Body

| Field        | Type    | Required | Description                           |
| ------------ | ------- | -------- | ------------------------------------- |
| `code`       | string  | Yes      | The coupon code to validate           |
| `product_id` | integer | Yes      | The product ID to apply the coupon to |
| `quantity`   | integer | Yes      | The purchase quantity (min: 1)        |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://embed.rmz.gg/api/embed/apply-coupon" \
    -H "X-Embed-Key: your_embed_public_key" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "SAVE20",
      "product_id": 42,
      "quantity": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://embed.rmz.gg/api/embed/apply-coupon", {
    method: "POST",
    headers: {
      "X-Embed-Key": "your_embed_public_key",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      code: "SAVE20",
      product_id: 42,
      quantity: 1
    })
  });

  const { data } = await response.json();
  console.log("Discount:", data.discount_amount);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://embed.rmz.gg/api/embed/apply-coupon",
      headers={
          "X-Embed-Key": "your_embed_public_key",
          "Content-Type": "application/json"
      },
      json={
          "code": "SAVE20",
          "product_id": 42,
          "quantity": 1
      }
  )

  data = response.json()["data"]
  print(f"Discount: {data['discount_amount']}")
  ```

  ```php PHP theme={null}
  $response = Http::withHeaders([
      'X-Embed-Key' => 'your_embed_public_key',
  ])->post('https://embed.rmz.gg/api/embed/apply-coupon', [
      'code' => 'SAVE20',
      'product_id' => 42,
      'quantity' => 1,
  ]);

  $data = $response->json()['data'];
  echo "Discount: " . $data['discount_amount'];
  ```
</CodeGroup>

### Success Response (200)

```json theme={null}
{
  "success": true,
  "data": {
    "coupon_id": 15,
    "code": "SAVE20",
    "type": "percentage",
    "amount": 20.0,
    "discount_amount": 29.80,
    "payment_restrictions": []
  }
}
```

### Response Fields

| Field                  | Type    | Description                                                                          |
| ---------------------- | ------- | ------------------------------------------------------------------------------------ |
| `coupon_id`            | integer | Internal coupon ID                                                                   |
| `code`                 | string  | The coupon code                                                                      |
| `type`                 | string  | Coupon type: `percentage` or `fixed`                                                 |
| `amount`               | float   | The coupon value (percentage or fixed amount)                                        |
| `discount_amount`      | float   | The calculated discount for the given product and quantity                           |
| `payment_restrictions` | array   | List of payment methods this coupon is restricted to (empty array = no restrictions) |

<Tip>
  If `payment_restrictions` is not empty, the customer can only use the listed payment methods when this coupon is applied. Display the restrictions in your UI to avoid confusion at checkout.
</Tip>

### Error Responses

**Validation error (422)**

```json theme={null}
{
  "success": false,
  "message": "Invalid request",
  "errors": {
    "code": ["The code field is required."],
    "product_id": ["The product id field is required."],
    "quantity": ["The quantity field is required."]
  }
}
```

**Invalid coupon (400)**

```json theme={null}
{
  "success": false,
  "message": "Invalid coupon"
}
```

**Coupon expired or inactive (400)**

```json theme={null}
{
  "success": false,
  "message": "Coupon is not active"
}
```

**Coupon usage limit reached (400)**

```json theme={null}
{
  "success": false,
  "message": "Coupon has reached maximum uses"
}
```

**Minimum cart value not met (400)**

```json theme={null}
{
  "success": false,
  "message": "Minimum order value is 100"
}
```

**Product not eligible (400)**

```json theme={null}
{
  "success": false,
  "message": "This coupon is not valid for this product"
}
```