> For the complete documentation index, see [llms.txt](https://yourpropfirm.gitbook.io/yourpropfirm-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yourpropfirm.gitbook.io/yourpropfirm-docs/integration/affiliate-coupon-integration.md).

# Affiliate Coupon Integration

This guide explains how to validate affiliate coupon codes during checkout and correctly attribute commissions to affiliate partners.

#### Swagger

```
https://affiliates.production.quant-technology.team/swagger-ui/index.html
```

#### API

```
https://affiliates.production.quant-technology.team/api/v1
```

#### Integration Flow

1. Customer enters a coupon code during checkout
2. Your backend calls the coupon validation endpoint
3. If the code is invalid, show the error message to the customer
4. If valid, apply the discount and display the updated order total
5. Submit the order using the returned affiliate information

#### Authentication

The coupon validation endpoint uses a Service Token for authentication.

QTG will provide this token and it must be included in every request header.

```
X-Service-Token: <your-service-token>
```

Always call this endpoint from your server and never expose your service token in client side or browser code.

If you haven't received your service token yet, please contact QTG to receive it.

#### Validate a Coupon Code

Use this endpoint whenever a customer enters a coupon code before the order is placed.

**Endpoint:**

```
POST /coupons/validate
```

**Request Headers**

```
X-Service-Token: <your-service-token>
Content-Type: application/json
```

**Request Body**

| Field       | Type   | Required | Description                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
| couponCode  | string | Yes      | The coupon code entered by the customer                             |
| orderAmount | number | Yes      | The order total before any discount is applied                      |
| refCode     | string | No       | Affiliate referral code, if captured from a tracking link or cookie |
| productId   | string | No       | The product or plan identifier being purchased                      |

**Example Request**

json

```
{
  "couponCode": "JOIN10",
  "orderAmount": 299.00,
  "refCode": "johndoe",
  "productId": "6a0d85f90063c21e148c925e"
}
```

**Example Response**

json

```
{
  "valid": true,
  "couponCodeRequested": "JOIN10",
  "couponCodeApplied": "JOIN10",
  "discountSource": "COUPON", //"CAMPAIGN" "NONE"
  "discountType": "PERCENT",
  "discountValue": 20.00,
  "discountAmount": 59.80,
  "finalAmount": 239.20,
  "affiliateAttribution": { // affiliateAttribution can be null (e.g., unexpected server error path returns 200 with valid=false, affiliateAttribution=null) — clients should null-check.
    "attributed": true,
    "attributedTo": "REFCODE", //"COUPON"
    "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partnerDisplayName": "John Doe"
  },
  "errorMessage": null
}
```

**Responses**

| Code | Description                                            |
| ---- | ------------------------------------------------------ |
| 200  | Validation result returned                             |
| 400  | Invalid request                                        |
| 401  | Unauthorized - missing or invalid service token        |
| 403  | Forbidden - only SERVICE role can access this endpoint |

**Response Fields**

| Field                             | Description                                                                                   |
| --------------------------------- | --------------------------------------------------------------------------------------------- |
| valid                             | If false, no discount should be applied                                                       |
| couponCodeRequested               | The coupon code entered by the customer                                                       |
| couponCodeApplied                 | The coupon code actually applied by the system                                                |
| discountType                      | Discount type (PERCENT or FIXED\_AMOUNT)                                                      |
| discountValue                     | Raw discount value                                                                            |
| discountAmount                    | Calculated discount amount                                                                    |
| finalAmount                       | Final order total after discount                                                              |
| affiliateAttribution.attributed   | Indicates whether affiliate attribution was successful                                        |
| affiliateAttribution.partnerId    | Store and submit this value to ensure commission attribution                                  |
| affiliateAttribution.attributedTo | Source of the attribution REFCODE (direct referral) or COUPON (credited via coupon ownership) |
| errorMessage                      | Explanation when validation fails                                                             |

**Note on Affiliate Campaign Behavior**

In some cases, the system may apply a different coupon than what the customer entered. This happens when an active campaign promotion offers a better discount. For example, a customer enters JOIN10, but an active campaign HALLOWEEN (20% off) is applied instead.

When this happens:

* couponCodeRequested shows what the customer typed
* couponCodeApplied shows what was actually applied
* Affiliate commission is still attributed to the original partner

**Always use** couponCodeApplied **when recording the order on your side.**