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

# Discount Codes

Create and manage discount codes for payment links

Discount codes let you offer percentage-based or fixed-amount discounts on payment links. Create individual codes, bulk-generate batches, and validate codes at checkout time.

Discount code management requires **admin** permission. The `/validate` endpoint requires **read** permission, making it safe to call from client-side checkout flows.

## Authentication

```bash
Authorization: Bearer asp_xxx
```

Base URL: `https://platform-api.anyspend.com/api/v1`

## Endpoints

### List Discount Codes

List all discount codes with optional filtering and pagination.

Search by code string (case-insensitive partial match).

Filter by active status. Omit to return all codes.

Page number for pagination (default: `1`).

Results per page (default: `20`, max: `100`).

**cURL**

```bash
    curl -X GET "https://platform-api.anyspend.com/api/v1/discount-codes?search=SUMMER&active=true&limit=10" \
      -H "Authorization: Bearer asp_xxx"
    ```
  **SDK**

```typescript
    import { AnySpendPlatformClient } from "@b3dotfun/sdk/anyspend/platform";

    const platform = new AnySpendPlatformClient(process.env.ANYSPEND_API_KEY!);
    const codes = await platform.discountCodes.list({
      search: "SUMMER",
      active: true,
      limit: 10,
    });
    ```

**Response**

```json
{
  "success": true,
  "data": [
    {
      "id": "dc_abc123",
      "code": "SUMMER25",
      "type": "percentage",
      "value": 25,
      "payment_link_id": "pl_xyz789",
      "max_uses": 100,
      "current_uses": 42,
      "min_order_amount": "5000000",
      "expires_at": "2026-09-01T00:00:00Z",
      "is_active": true,
      "created_at": "2026-06-01T00:00:00Z",
      "updated_at": "2026-06-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}
```

---

### Create Discount Code

Create a single discount code.

The discount code string (e.g., `SUMMER25`). Must be unique. Automatically uppercased.

Discount type: `percentage` or `fixed`.

Discount value. For `percentage`, a number between 1-100. For `fixed`, the amount in the token's smallest unit (e.g., `5000000` for 5 USDC).

Restrict this code to a specific payment link. If omitted, the code works on all payment links.

Maximum number of times this code can be redeemed. Omit for unlimited uses.

Minimum order amount required to use this code, in the token's smallest unit.

ISO 8601 expiration timestamp. Omit for a code that never expires.

**cURL**

```bash
    curl -X POST https://platform-api.anyspend.com/api/v1/discount-codes \
      -H "Authorization: Bearer asp_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "code": "SUMMER25",
        "type": "percentage",
        "value": 25,
        "payment_link_id": "pl_xyz789",
        "max_uses": 100,
        "min_order_amount": "5000000",
        "expires_at": "2026-09-01T00:00:00Z"
      }'
    ```
  **SDK**

```typescript
    const code = await platform.discountCodes.create({
      code: "SUMMER25",
      type: "percentage",
      value: 25,
      payment_link_id: "pl_xyz789",
      max_uses: 100,
      min_order_amount: "5000000",
      expires_at: "2026-09-01T00:00:00Z",
    });
    ```

**Response**

```json
{
  "success": true,
  "data": {
    "id": "dc_abc123",
    "code": "SUMMER25",
    "type": "percentage",
    "value": 25,
    "payment_link_id": "pl_xyz789",
    "max_uses": 100,
    "current_uses": 0,
    "min_order_amount": "5000000",
    "expires_at": "2026-09-01T00:00:00Z",
    "is_active": true,
    "created_at": "2026-02-27T12:00:00Z",
    "updated_at": "2026-02-27T12:00:00Z"
  }
}
```

---

### Update Discount Code

Update an existing discount code. All fields are optional.

**cURL**

```bash
    curl -X PATCH https://platform-api.anyspend.com/api/v1/discount-codes/dc_abc123 \
      -H "Authorization: Bearer asp_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "max_uses": 200,
        "expires_at": "2026-12-31T23:59:59Z"
      }'
    ```
  **SDK**

```typescript
    const updated = await platform.discountCodes.update("dc_abc123", {
      max_uses: 200,
      expires_at: "2026-12-31T23:59:59Z",
    });
    ```

---

### Delete Discount Code

Permanently delete a discount code. Active sessions using this code will not be affected.

**cURL**

```bash
    curl -X DELETE https://platform-api.anyspend.com/api/v1/discount-codes/dc_abc123 \
      -H "Authorization: Bearer asp_xxx"
    ```
  **SDK**

```typescript
    await platform.discountCodes.delete("dc_abc123");
    ```

---

### Validate Discount Code

Validate a discount code against a payment link and order amount. Returns the discount details if valid, or an error message explaining why the code is invalid.

The discount code to validate.

The payment link the code is being applied to.

The order amount in the token's smallest unit, used to check `min_order_amount` and calculate the discounted total.

**cURL**

```bash
    curl -X POST https://platform-api.anyspend.com/api/v1/discount-codes/validate \
      -H "Authorization: Bearer asp_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "code": "SUMMER25",
        "payment_link_id": "pl_xyz789",
        "amount": "20000000"
      }'
    ```
  **SDK**

```typescript
    const result = await platform.discountCodes.validate({
      code: "SUMMER25",
      payment_link_id: "pl_xyz789",
      amount: "20000000",
    });

    if (result.valid) {
      console.log("Discount:", result.discount_amount);
      console.log("New total:", result.final_amount);
    } else {
      console.log("Invalid:", result.error);
    }
    ```

**Valid Response**

```json
{
  "success": true,
  "data": {
    "valid": true,
    "code": "SUMMER25",
    "type": "percentage",
    "value": 25,
    "discount_amount": "5000000",
    "final_amount": "15000000"
  }
}
```

**Invalid Response**

```json
{
  "success": true,
  "data": {
    "valid": false,
    "error": "Code has reached maximum number of uses"
  }
}
```

The validate endpoint does **not** consume a use. Uses are only counted when a payment is completed with the discount applied.

---

### Batch Create Discount Codes

Bulk-create multiple discount codes at once with shared configuration. Useful for generating promotional campaigns or unique single-use codes.

Array of code strings to create. Each must be unique.

Discount type applied to all codes: `percentage` or `fixed`.

Discount value applied to all codes.

Restrict all codes to a specific payment link.

Maximum uses per code. Set to `1` for single-use codes.

Minimum order amount for all codes.

ISO 8601 expiration timestamp for all codes.

**cURL**

```bash
    curl -X POST https://platform-api.anyspend.com/api/v1/discount-codes/batch \
      -H "Authorization: Bearer asp_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "codes": ["PROMO-A1B2", "PROMO-C3D4", "PROMO-E5F6"],
        "type": "fixed",
        "value": 2000000,
        "payment_link_id": "pl_xyz789",
        "max_uses": 1,
        "expires_at": "2026-06-30T23:59:59Z"
      }'
    ```
  **SDK**

```typescript
    const batch = await platform.discountCodes.batchCreate({
      codes: ["PROMO-A1B2", "PROMO-C3D4", "PROMO-E5F6"],
      type: "fixed",
      value: 2000000,
      payment_link_id: "pl_xyz789",
      max_uses: 1,
      expires_at: "2026-06-30T23:59:59Z",
    });

    console.log(`Created ${batch.created} codes`);
    ```

**Response**

```json
{
  "success": true,
  "data": {
    "created": 3,
    "codes": [
      { "id": "dc_001", "code": "PROMO-A1B2" },
      { "id": "dc_002", "code": "PROMO-C3D4" },
      { "id": "dc_003", "code": "PROMO-E5F6" }
    ]
  }
}
```

---

## Discount Code Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier (e.g., `dc_abc123`) |
| `code` | `string` | The discount code string (uppercased) |
| `type` | `string` | `percentage` or `fixed` |
| `value` | `number` | Discount value (percentage 1-100, or fixed amount in smallest unit) |
| `payment_link_id` | `string \| null` | Restricted payment link, or `null` for all links |
| `max_uses` | `number \| null` | Maximum redemptions, or `null` for unlimited |
| `current_uses` | `number` | Number of times redeemed so far |
| `min_order_amount` | `string \| null` | Minimum order amount required |
| `expires_at` | `string \| null` | ISO 8601 expiration, or `null` for no expiration |
| `is_active` | `boolean` | Whether the code is currently usable |
| `created_at` | `string` | ISO 8601 creation timestamp |
| `updated_at` | `string` | ISO 8601 last update timestamp |

## Validation Rules

A discount code is considered **invalid** if any of the following are true:

| Condition | Error Message |
|-----------|---------------|
| Code does not exist | `Invalid discount code` |
| Code is inactive (`is_active: false`) | `Discount code is not active` |
| Code has expired | `Discount code has expired` |
| `current_uses >= max_uses` | `Code has reached maximum number of uses` |
| Code is restricted to a different payment link | `Code is not valid for this payment link` |
| Order amount is below `min_order_amount` | `Order amount is below minimum required` |