---
title: "Create Coupon"
source_url: https://docs.rapyd.net/en/create-coupon.html
lang: en
---

# Create Coupon

Create a coupon.

This method triggers the **Coupon Created** webhook. This webhook contains the same information as the response.

> **Note:**
>
> - The code samples include successful requests (200) and bad requests (400).
>
>   - For error messages that appear due to bad requests (400), see:
>
>     - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors")
>     - [Coupon Errors](https://docs.rapyd.net/en/coupon-errors.md "Coupon Errors")
>   - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors").

### Parameters

### 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**.
- - idempotency
  - A unique key that prevents the platform from creating the same object twice.

    See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency").
- - 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).

### Request Body 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.

    Required when `percent_off` is not set.
- - currency
  - Three-letter ISO 4217 code for the currency used in the `amount_off` parameter.

    Required when `amount_off` is set.
- - 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.

    Relevant when `duration` is **repeating** and `redeem_by` is not set.
- - discount_validity_in_months
  - The number of months after the discount is created that it can be used.

    Relevant when `discount_valid_until` is not set.
- - 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").

    Relevant when `discount_validity_in_months` is not set.
- - 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.

    Required when `duration` is **repeating**.
- - id
  - Unique ID for this coupon. English alphanumeric characters with no special characters except underscore. If the client 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 and orders that the coupon is used in 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.

    Required when `amount_off` is not set.
- - 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`.

### 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;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      var requestObj = new
                      {
                          duration = "repeating",
                          duration_in_months = 3,
                          max_redemptions = 0,
                          metadata = new
                          {
                              merchant_defined = true

                          },
                          percent_off = 10,
                          redeem_by = 0,
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/coupons", request);

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```javascript
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {
            duration: 'repeating',
            duration_in_months: 3,
            max_redemptions: 0,
            metadata: {
              merchant_defined: true
            },
            percent_off: 10,
            redeem_by: 0
          };
          const result = await makeRequest('POST', '/v1/coupons', body);

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```php
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      $body = [
          "duration" => "repeating",
          "duration_in_months" => 3,
          "max_redemptions" => 0,
          "metadata" => array(
              "merchant_defined" => true
          ),
          "percent_off" => 10,
          "redeem_by" => 0
      ];

      try {
          $object = make_request('post', '/v1/coupons', $body);
          var_dump($object);
      } catch(Exception $e) {
          echo "Error =>$e";
      }
      ?>
      ```
- - Python

    - ```python
      from pprint import pprint

      from utilities import make_request

      coupon = {
          "duration": "repeating",
          "duration_in_months": 3,
          "max_redemptions": 0,
          "metadata": {
              "merchant_defined": True
          },
          "percent_off": 10,
          "redeem_by": 0
      }
      result = make_request(method='post', path='/v1/coupons', body=coupon)
      pprint(result)
      ```

- /v1/coupons

- Percent Off
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "duration": "repeating",
      "duration_in_months": 3,
      "id": "",
      "max_redemptions": 10,
      "percent_off": 10,
      "redeem_by": 0
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "36d538be-c787-494c-b858-34e7c0e206bd"
      },
      "data": {
          "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
      }
  }
  ```

- Amount Off
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "amount_off": 2.25,
      "currency": "USD",
      "duration": "repeating",
      "duration_in_months": 3,
      "id": "",
      "max_redemptions": 10,
      "redeem_by": 0
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "5d09b146-fc7e-4509-b711-71bcd842e718"
      },
      "data": {
          "id": "coupon_64016edee479bb60bb6eb0f869c96d07",
          "amount_off": 2.25,
          "created": 1762091524,
          "currency": "USD",
          "duration": "repeating",
          "duration_in_months": 3,
          "max_redemptions": 10,
          "metadata": {},
          "percent_off": 0,
          "redeem_by": 0,
          "times_redeemed": 0,
          "discount_valid_until": 0,
          "discount_validity_in_months": 0,
          "discount_duration_in_uses": 0,
          "description": "",
          "valid": false
      }
  }
  ```

- One Use
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "amount_off": 2.75,
      "currency": "USD",
      "duration": "repeating",
      "duration_in_months": 1,
      "discount_duration_in_uses": 1,
      "max_redemptions": 1
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "adef7239-5688-4d28-ab18-0de89b57537c"
      },
      "data": {
          "id": "coupon_b1d1eb5bda5a50058cf198d0948afae0",
          "amount_off": 2.75,
          "created": 1762091613,
          "currency": "USD",
          "duration": "repeating",
          "duration_in_months": 1,
          "max_redemptions": 1,
          "metadata": {},
          "percent_off": 0,
          "redeem_by": 0,
          "times_redeemed": 0,
          "discount_valid_until": 0,
          "discount_validity_in_months": 0,
          "discount_duration_in_uses": 1,
          "description": "",
          "valid": true
      }
  }
  ```

- Duration - Repeating for 5 months
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "currency": "USD",
      "duration": "repeating",
      "duration_in_months": 5,
      "max_redemptions": 10,
      "percent_off": 20
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "fbcc9d02-fb93-4946-86fb-ecfe5378a326"
      },
      "data": {
          "id": "coupon_3d7c387f8158b24813c15f5704f9e6c1",
          "amount_off": 0,
          "created": 1762094734,
          "currency": "USD",
          "duration": "repeating",
          "duration_in_months": 5,
          "max_redemptions": 10,
          "metadata": {},
          "percent_off": 20,
          "redeem_by": 0,
          "times_redeemed": 0,
          "discount_valid_until": 0,
          "discount_validity_in_months": 0,
          "discount_duration_in_uses": 0,
          "description": "",
          "valid": false
      }
  }
  ```

- Duration - Forever
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "amount_off": 2.25,
      "currency": "USD",
      "duration": "forever",
      "max_redemptions": 1
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "0753c2ef-96d3-4828-a546-6fef11629ebb"
      },
      "data": {
          "id": "coupon_e21fa4476472cfe2de3fbf08a179c62a",
          "amount_off": 2.25,
          "created": 1762094788,
          "currency": "USD",
          "duration": "forever",
          "duration_in_months": 0,
          "max_redemptions": 1,
          "metadata": {},
          "percent_off": 0,
          "redeem_by": 0,
          "times_redeemed": 0,
          "discount_valid_until": 0,
          "discount_validity_in_months": 0,
          "discount_duration_in_uses": 0,
          "description": "",
          "valid": true
      }
  }
  ```

- Bad Request - Duration Value Not Valid
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "amount_off": 2.25,
      "currency": "USD",
      "duration": "repeat",
      "duration_in_months": 3,
      "id": "",
      "max_redemptions": 0,
      "redeem_by": 0
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "INVALID_COUPON_DURATION",
          "status": "ERROR",
          "message": "The request tried to create a coupon, but the value for the 'duration' parameter was not recognized. The request was rejected. Corrective action: Set 'duration' to one of the following values: 'forever', 'repeating'",
          "response_code": "INVALID_COUPON_DURATION",
          "operation_id": "9b3e76ef-f65c-4d90-84e6-e7b235a0ce25"
      }
  }
  ```

- Bad Request - Negative Duration Value
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/coupons' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "amount_off": 2.25,
      "currency": "USD",
      "duration": "repeating",
      "duration_in_months": -2,
      "id": "",
      "max_redemptions": 0,
      "redeem_by": 0
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "INVALID_COUPON_DURATION_IN_MONTH",
          "status": "ERROR",
          "response_code": "INVALID_COUPON_DURATION_IN_MONTH",
          "operation_id": "0f42f0de-a3a0-4c8e-a434-1dca0e450648"
      }
  }
  ```