--- title: "List Coupons" source_url: https://docs.rapyd.net/en/list-coupons.html lang: en --- # List Coupons Retrieve a list of all coupons. You can filter the list with query parameters. ### Parameters ### Request Query Parameters - - ending_before - The ID of the coupon created after the last coupon you want to retrieve. - - limit - The maximum number of coupons to return. Range: 1-100. 10 - - starting_after - The ID of the coupon created before the first coupon you want to retrieve. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters - - amount_off - The amount of money to subtract from the payment. Decimal. Range: Positive decimal number, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. - - created - When the coupon was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - currency - Three-letter ISO 4217 code for the currency used in the `amount_off` parameter. - - description - Description of the coupon. - - discount_duration_in_uses - The number of times that the coupon can be redeemed by a specific customer or subscription. - - discount_validity_in_months - The number of months after the discount is created that it can be used. - - discount_valid_until - The final date that a discount can be used, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - duration - Determines how long the discount remains in effect. One of the following: - **forever** - **repeating** - - duration_in_months - Determines the number of months that the coupon remains in effect after its creation. Integer. - - id - Unique ID for this coupon. English alphanumeric characters with no special characters except underscore. If the merchant does not define an ID, Rapyd generates a string starting with **coupon_**. - - max_redemptions - Determines the number of times the coupon can be redeemed. The number of customers, subscriptions or orders that the coupon is applied to cannot exceed this number. Integer. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - percent_off - Determines the size of the discount, measured in percent. Integer. Range: 1-100. - - redeem_by - The last time at which the coupon can be redeemed, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). After the `redeem_by` date, the coupon can no longer be applied to new customers. 'redeem_by' takes precedence over the setting of `discount_duration_in_uses` and `duration_in_months`. - - times_redeemed - Indicates the number of times the coupon has been applied to a customer, subscription or invoice. If the discount has been used more than one time by a customer, subscription or invoice, the number of redemptions after the first is also added to this value. Integer. When this value equals `max_redemptions`, the coupon becomes no longer valid. - - valid - Indicates whether the coupon can be redeemed. ### Code Samples - - .NET - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/coupons"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest( 'GET', '/v1/coupons' ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('get', '/v1/coupons'); var_dump($object); } catch(Exception $e) { echo "Error =>$e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request result = make_request(method='get', path='/v1/coupons') pprint(result) ``` - /v1/coupons - List Coupons - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/coupons?limit=2' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "b6dbd9a4-88eb-405f-97f1-593254189a16" }, "data": [ { "id": "coupon_ec743a04cbaf362e55695efe868d4c3b", "amount_off": 2.75, "created": 1763464621, "currency": "USD", "duration": "repeating", "duration_in_months": 1, "max_redemptions": 1, "metadata": {}, "percent_off": 0, "redeem_by": 0, "times_redeemed": 1, "discount_valid_until": 0, "discount_validity_in_months": 0, "discount_duration_in_uses": 1, "description": "", "valid": false }, { "id": "coupon_7b9934fcc584ef629d2dcad65cc0d39c", "amount_off": 0, "created": 1762175848, "currency": "", "duration": "repeating", "duration_in_months": 3, "max_redemptions": 10, "metadata": {}, "percent_off": 10, "redeem_by": 0, "times_redeemed": 0, "discount_valid_until": 0, "discount_validity_in_months": 0, "discount_duration_in_uses": 0, "description": "", "valid": true } ] } ```