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

# Create Discount

> Create a new discount code

# Create Discount

Creates a new discount code in the store. Requires the `write_discounts` scope.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.launchmystore.io/api/v1/discounts.json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "SUMMER20",
      "type": "percentage",
      "value": 20,
      "usage_limit": 500,
      "once_per_customer": true,
      "minimum_amount": 50,
      "starts_at": "2024-06-01T00:00:00Z",
      "ends_at": "2024-08-31T23:59:59Z"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.launchmystore.io/api/v1/discounts.json', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      code: 'SUMMER20',
      type: 'percentage',
      value: 20,
      usage_limit: 500,
      once_per_customer: true,
      minimum_amount: 50,
      starts_at: '2024-06-01T00:00:00Z',
      ends_at: '2024-08-31T23:59:59Z'
    })
  });
  ```
</CodeGroup>

## Body Parameters

<ParamField body="code" type="string" required>
  Unique discount code. A discount with an existing code is rejected.
</ParamField>

<ParamField body="type" type="string" required>
  Discount type. One of `percentage`, `fixed_amount`, `free_shipping`,
  `buy_x_get_y`.
</ParamField>

<ParamField body="value" type="number" required>
  Discount value. For `percentage`, enter `20` for 20%. For `fixed_amount`,
  enter the amount in the store's currency (e.g. `20` for 20.00). Ignored for
  `free_shipping`.
</ParamField>

<ParamField body="minimum_amount" type="number">
  Minimum order total required for the discount to apply.
</ParamField>

<ParamField body="usage_limit" type="integer">
  Maximum number of times the discount can be used across all customers.
  Defaults to `0` (unlimited) when omitted.
</ParamField>

<ParamField body="once_per_customer" type="boolean" default="false">
  When `true`, limits the discount to one use per customer.
</ParamField>

<ParamField body="product_ids" type="array">
  Array of product IDs the discount is restricted to. Omit to apply the
  discount store-wide.
</ParamField>

<ParamField body="starts_at" type="string">
  Start date (ISO 8601). Omit for no start constraint.
</ParamField>

<ParamField body="ends_at" type="string">
  End date (ISO 8601). Omit for no expiration.
</ParamField>

<Note>
  The merchant dashboard supports additional discount capabilities —
  minimum quantity, buy-X-get-Y quantities and free-item rewards, and
  new-customer eligibility. These are configured through the merchant
  surface and are not part of the OAuth App-API create body; any extra
  fields sent here are ignored.
</Note>

## Response

The created discount is returned under `data.discount` in the standard
response envelope.

```json theme={null}
{
  "status": 201,
  "state": "success",
  "message": null,
  "data": {
    "discount": {
      "couponId": "9f1c2e7a-3b4d-4f5a-8c6b-1d2e3f4a5b6c",
      "code": "SUMMER20",
      "type": "Percentage",
      "status": "Active",
      "discountPercentage": 20,
      "discountAmount": null,
      "minOrderTotal": 50,
      "startDate": "2024-06-01T00:00:00Z",
      "endDate": "2024-08-31T23:59:59Z",
      "totalCoupons": 500,
      "usesPerCustomer": 1,
      "applyOnProducts": [],
      "storeId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "createdAt": "2024-05-15T10:00:00Z",
      "updatedAt": "2024-05-15T10:00:00Z"
    }
  },
  "count": null,
  "pagination": null
}
```

## Errors

| Status | `state` | Message                                                   |
| ------ | ------- | --------------------------------------------------------- |
| `400`  | `error` | `code is required` (missing code)                         |
| `400`  | `error` | `Discount with this code already exists`                  |
| `400`  | `error` | Validation error (invalid `type`, negative `value`, etc.) |
| `401`  | `error` | Invalid or missing access token                           |
| `403`  | `error` | App is missing the `write_discounts` scope                |