# List Coupons

- **URL:** https://marketplace.gohighlevel.com/docs/ghl/payments/list-coupons
- **Summary:** The 'List Coupons' API allows you to retrieve a list of all coupons available in your location. Use this endpoint to view all promotional offers and special discounts for your customers.

[Skip to main content](https://marketplace.gohighlevel.com/docs/ghl/payments/list-coupons#__docusaurus_skipToContent_fallback)

Version: v3

List Coupons
============

GET 

https://services.leadconnectorhq.com/payments/coupon/list

Copy for LLMView as MarkdownOpen in ClaudeOpen in ChatGPTOpen in Cursor

The "List Coupons" API allows you to retrieve a list of all coupons available in your location. Use this endpoint to view all promotional offers and special discounts for your customers.

### Requirements

#### Scope(s)

`payments/coupons.readonly`

#### Auth Method(s)

`OAuth Access Token``Private Integration Token`

#### Token Type(s)

`Sub-Account Token`

Request[​](https://marketplace.gohighlevel.com/docs/ghl/payments/list-coupons#request "Direct link to request")

### Header Parameters

**Version** stringrequired

**Possible values:** \[`v3`\]

API Version

### Query Parameters

**altId** stringrequired

Location Id

**Example:** `BQdAwxa0ky1iK2sstLGJ`

**altType** stringrequired

**Possible values:** \[`location`\]

Alt Type

**Example:** `location`

**limit** number

Maximum number of coupons to return

Default value:`100`

**Example:** `10`

**offset** number

Number of coupons to skip for pagination

Default value:`0`

**Example:** `0`

**status** string

**Possible values:** \[`scheduled`, `active`, `expired`\]

Filter coupons by status

**Example:** `active`

**search** string

Search term to filter coupons by name or code

**Example:** `DEAL50`

Responses[​](https://marketplace.gohighlevel.com/docs/ghl/payments/list-coupons#responses "Direct link to Responses")

*   200
*   422

Successful response

*   application/json

*   Schema
*   Example (auto)

**Schema**

**data** object\[\]required

Array of coupon objects

*   Array \[\
    \
\
**_id**stringrequired\
\
Unique MongoDB identifier for the coupon\
\
**Example:** `67f6c132d9485f9dacd5f123`\
\
**usageCount**numberrequired\
\
Number of times the coupon has been used\
\
**Example:** `12`\
\
**limitPerCustomer**numberrequired\
\
Maximum number of times a customer can use this coupon (0 for unlimited)\
\
**Example:** `5`\
\
**altId**stringrequired\
\
Location Id\
\
**Example:** `79t07PzK8Tvf73d12312`\
\
**altType**stringrequired\
\
Type of entity\
\
**Example:** `location`\
\
**name**stringrequired\
\
Display name of the coupon\
\
**Example:** `NEWT6`\
\
**code**stringrequired\
\
Redemption code for the coupon\
\
**Example:** `NEWT6`\
\
**discountType**stringrequired\
\
Type of discount (percentage or amount)\
\
**Possible values:** \[`percentage`, `amount`\]\
\
**Example:** `percentage`\
\
**discountValue**numberrequired\
\
Value of the discount (percentage or fixed amount)\
\
**Example:** `25`\
\
**status**stringrequired\
\
Current status of the coupon\
\
**Possible values:** \[`scheduled`, `active`, `expired`\]\
\
**Example:** `scheduled`\
\
**startDate**stringrequired\
\
Date when the coupon becomes active\
\
**Example:** `2025-04-30T18:30:00.000Z`\
\
**endDate**string\
\
End date when the coupon expires\
\
**Example:** `2025-05-30T18:30:00.000Z`\
\
**applyToFuturePayments**booleanrequired\
\
Indicates if the coupon applies to future recurring payments\
\
**Example:** `true`\
\
**applyToFuturePaymentsConfig** objectrequired\
\
Configuration for how the coupon applies to future payments\
\
**type**stringrequired\
\
Type of future payments configuration\
\
**Possible values:** \[`forever`, `fixed`\]\
\
**Example:** `fixed`\
\
**duration**number\
\
Duration value for fixed type configurations\
\
**Example:** `3`\
\
**durationType**string\
\
Duration type for fixed configurations (e.g. months)\
\
**Example:** `months`\
\
**productIds**string\[\]\
\
Product Ids\
\
**Example:** `["6241712be68f7a98102ba272"]`\
\
**priceIds**string\[\]\
\
Price Ids\
\
**Example:** `["6241712be68f7a98102ba272"]`\
\
**variantIds**string\[\]\
\
Variant Ids\
\
**Example:** `["6241712be68f7a98102ba272"]`\
\
**userId**string\
\
User ID associated with the coupon (if applicable)\
\
**Example:** `q0m15dTLGeiGOXG123123`\
\
**createdAt**stringrequired\
\
Creation timestamp\
\
**Example:** `2025-04-09T18:49:22.026Z`\
\
**updatedAt**stringrequired\
\
Last update timestamp\
\
**Example:** `2025-04-09T18:49:22.026Z`\
\
*   \]
    

**totalCount**numberrequired

Total number of coupons matching the query criteria

**Example:** `20`

**traceId**stringrequired

Unique identifier for tracing this API request

**Example:** `c667b18d-8f5e-44cf-a914`

    {  "data": [    {      "_id": "67f6c132d9485f9dacd5f123",      "usageCount": 12,      "limitPerCustomer": 5,      "altId": "79t07PzK8Tvf73d12312",      "altType": "location",      "name": "NEWT6",      "code": "NEWT6",      "discountType": "percentage",      "discountValue": 25,      "status": "scheduled",      "startDate": "2025-04-30T18:30:00.000Z",      "endDate": "2025-05-30T18:30:00.000Z",      "applyToFuturePayments": true,      "applyToFuturePaymentsConfig": {        "type": "fixed",        "duration": 3,        "durationType": "months"      },      "productIds": [        "6241712be68f7a98102ba272"      ],      "priceIds": [        "6241712be68f7a98102ba272"      ],      "variantIds": [        "6241712be68f7a98102ba272"      ],      "userId": "q0m15dTLGeiGOXG123123",      "createdAt": "2025-04-09T18:49:22.026Z",      "updatedAt": "2025-04-09T18:49:22.026Z"    }  ],  "totalCount": 20,  "traceId": "c667b18d-8f5e-44cf-a914"}

Unprocessable Entity

*   application/json

*   Schema
*   Example (auto)

**Schema**

**statusCode**number

**Example:** `422`

**message**string\[\]

**Example:** `["Unprocessable Entity"]`

**error**string

**Example:** `Unprocessable Entity`

    {  "statusCode": 422,  "message": [    "Unprocessable Entity"  ],  "error": "Unprocessable Entity"}

Share your feedback
-------------------

★★★★★

#### Authorization: Authorization

**name:** [Authorization](https://marketplace.gohighlevel.com/docs/ghl/payments/payments-api#authentication)
**type:** http**scopes:** `payments/coupons.readonly`**scheme:** bearer**bearerFormat:** JWT**in:** header**description:** Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

*   curl
*   nodejs
*   python
*   php
*   java
*   go
*   ruby
*   powershell

*   CURL

    curl -L 'https://services.leadconnectorhq.com/payments/coupon/list?altId=BQdAwxa0ky1iK2sstLGJ&altType=location&limit=100&status=active&search=DEAL50' \-H 'Accept: application/json' \-H 'Authorization: Bearer <Authorization>'

RequestCollapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

altId — queryrequired

altType — queryrequired\---location

Version — headerrequired\---v3

Show optional parameters

limit — query

offset — query

status — query\---scheduledactiveexpired

search — query

Send API Request

ResponseClear

Click the `Send API Request` button above and see the response here!