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

# Verify coupon

> Validate a coupon code and calculate the discount amount before applying it to an order.

## Request

```http theme={null}
POST /coupons/verify
Content-Type: application/json
x-shop-id: {shopId}
Authorization: Bearer {token}
{
  "code": "SUMMER20",
  "orderId": "67890abcdef1234567890abc"
}
```

## Headers

| Header          | Type   | Description                                            |
| --------------- | ------ | ------------------------------------------------------ |
| `Content-Type`  | string | Always set to `application/json`.                      |
| `x-shop-id`     | string | Shop identifier to associate the user with your store. |
| `Authorization` | string | Optional Bearer token for authenticated requests.      |

<Note>
  This endpoint supports both authenticated and unauthenticated requests.
  Authentication is optional but recommended to validate user-specific coupon
  usage limits.
</Note>

## Body parameters

| Field     | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `code`    | string | Yes      | Coupon code to verify (case-insensitive).        |
| `orderId` | string | No       | Order ID to validate coupon against order total. |

## Successful response

```json theme={null}
{
    "status": 200,
    "success": true,
    "message": "Coupon is valid",
    "data": {
        "_id": "67890abcdef1234567890abc",
        "code": "SUMMER20",
        "type": "percentage",
        "discount": 20,
        "discountAmount": 200,
        "minimumOrderAmount": 500,
        "startDate": "2025-01-01T00:00:00.000Z",
        "endDate": "2025-12-31T23:59:59.000Z",
        "title": "20% off order above 500"
    }
}
```

### Response fields

| Field                | Type   | Description                                              |
| -------------------- | ------ | -------------------------------------------------------- |
| `_id`                | string | Unique coupon identifier.                                |
| `code`               | string | Coupon code.                                             |
| `type`               | string | Coupon type: `fixed` or `percentage`.                    |
| `discount`           | number | Discount value (fixed amount or percentage).             |
| `discountAmount`     | number | Calculated discount amount based on order subtotal.      |
| `minimumOrderAmount` | number | Minimum order amount required to use the coupon.         |
| `startDate`          | string | Date when the coupon becomes active.                     |
| `endDate`            | string | Date when the coupon expires.                            |
| `title`              | string | Human-readable description of the coupon discount offer. |

## Validation checks

The endpoint performs the following validations:

<Check>Coupon exists and is active</Check>
<Check>Coupon belongs to the specified shop</Check>
<Check>Coupon is within valid date range (between start and end dates)</Check>
<Check>Global usage limit has not been exceeded</Check>

<Check>
  Per-user usage limit has not been exceeded (for authenticated users)
</Check>

<Check>Order meets minimum amount requirement (if orderId provided)</Check>

## Error responses

### Invalid coupon code

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

### Coupon expired

```json theme={null}
{
    "status": 400,
    "success": false,
    "message": "Coupon has expired"
}
```

### Minimum order not met

```json theme={null}
{
    "status": 400,
    "success": false,
    "message": "Minimum order amount of 500 required to use this coupon"
}
```

### Usage limit reached

```json theme={null}
{
    "status": 400,
    "success": false,
    "message": "You have already used this coupon 1 time(s)"
}
```


## OpenAPI

````yaml POST /coupons/verify
openapi: 3.1.0
info:
  title: Salesive Store API
  description: >-
    REST interface for querying products, categories, and merchandising banners
    exposed by Salesive storefronts.
  version: 1.0.0
servers:
  - description: Production
    url: https://store.salesive.com/api/v1
security:
  - BearerAuth: []
    ShopIdHeader: []
paths:
  /coupons/verify:
    post:
      summary: Verify coupon
      description: >-
        Validate a coupon code and calculate the discount amount before applying
        it to an order.
      parameters:
        - $ref: '#/components/parameters/XShopIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - code
              properties:
                code:
                  type: string
                  description: Coupon code to verify (case-insensitive).
                  example: SUMMER20
                orderId:
                  type: string
                  description: Optional order ID to validate coupon against order total.
                  example: 67890abcdef1234567890abc
      responses:
        '200':
          description: Coupon is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyCouponResponse'
        '400':
          description: Coupon validation failed (expired, usage limit reached, etc.).
        '404':
          description: Invalid coupon code.
      security: []
components:
  parameters:
    XShopIdHeader:
      name: x-shop-id
      in: header
      description: >-
        Optional identifier that scopes responses to a specific storefront when
        the referer cannot be inferred.
      required: false
      schema:
        type: string
  schemas:
    VerifyCouponResponse:
      type: object
      required:
        - status
        - success
        - message
        - data
      properties:
        status:
          type: integer
          example: 200
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Coupon is valid
        data:
          type: object
          properties:
            _id:
              type: string
              description: Unique coupon identifier.
            code:
              type: string
              description: Coupon code.
            type:
              type: string
              enum:
                - fixed
                - percentage
              description: Coupon type.
            discount:
              type: number
              description: Discount value (fixed amount or percentage).
            discountAmount:
              type: number
              description: Calculated discount amount based on order subtotal.
            minimumOrderAmount:
              type: number
              description: Minimum order amount required to use the coupon.
            startDate:
              type: string
              format: date-time
              description: Date when the coupon becomes active.
            endDate:
              type: string
              format: date-time
              description: Date when the coupon expires.
            title:
              type: string
              description: Human-readable description of the coupon discount offer.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued by the Salesive Store API for authenticated shoppers.
    ShopIdHeader:
      type: apiKey
      in: header
      name: x-shop-id
      description: >-
        Optional storefront identifier sent as a header to scope responses to a
        specific shop. Try It requests remember this value once provided.

````