Create Coupon

Create a coupon.

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

Parameters

Request Header Parameters

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.
  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.
- 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. 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.
- 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.
- 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.
- 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. 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

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

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
$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

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 -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'
-d '{
    "duration": "repeating",
    "duration_in_months": 3,
    "max_redemptions": 0,
    "metadata": {
        "merchant_defined": true
    },
    "percent_off": 10,
    "redeem_by": 0
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "a582f08b-9d24-4742-b938-2ead31384886"
    },
    "data": {
        "id": "coupon_72b8f33846b06f9e7fb0d12cccf98061",
        "amount_off": 0,
        "created": 1646817710,
        "currency": "",
        "duration": "repeating",
        "duration_in_months": 3,
        "max_redemptions": 0,
        "metadata": {
            "merchant_defined": true
        },
        "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": false
    }
}

Amount off

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'
-d '{
    "amount_off": 2,
    "currency": "USD",
    "duration": "repeating",
    "duration_in_months": 3,
    "id": "",
    "max_redemptions": 0,
    "metadata": {
        "merchant_defined": true
    },
    "percent_off": null,
    "redeem_by": 0
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "4136bb02-a810-4fa4-93b3-6e9c9db3d635"
    },
    "data": {
        "id": "coupon_4dad14cea027ceb54a6c39837744d91c",
        "amount_off": 2,
        "created": 1646818171,
        "currency": "USD",
        "duration": "repeating",
        "duration_in_months": 3,
        "max_redemptions": 0,
        "metadata": {
            "merchant_defined": true
        },
        "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 -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'
-d '{
    "amount_off": 2,
    "currency": "USD",
    "duration": "repeating",
    "duration_in_months": 1,
    "discount_duration_in_uses": 1,
    "max_redemptions": 1,
    "metadata": {
        "merchant_defined": true
    },
    "percent_off": null,
    "redeem_by": 0
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "5cc78ea0-d657-4a16-a0f1-a4af2b8ac34d"
    },
    "data": {
        "id": "coupon_dc3d519ebfee0818d883686d516fc780",
        "amount_off": 2,
        "created": 1647155932,
        "currency": "USD",
        "duration": "repeating",
        "duration_in_months": 1,
        "max_redemptions": 1,
        "metadata": {
            "merchant_defined": true
        },
        "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 -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'
-d '{
    "currency": "USD",
    "duration": "repeating",
    "duration_in_months": 5,
    "max_redemptions": 0,
    "metadata": {
        "merchant_defined": true
    },
    "percent_off": 20,
    "redeem_by": 0
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "86cac233-444e-464c-878b-c10bbf94b13d"
    },
    "data": {
        "id": "coupon_71ac2a65139aced4ef0d09aec75e19ba",
        "amount_off": 0,
        "created": 1646825405,
        "currency": "USD",
        "duration": "repeating",
        "duration_in_months": 5,
        "max_redemptions": 0,
        "metadata": {
            "merchant_defined": true
        },
        "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 -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'
-d '{
    "amount_off": 2,
    "currency": "USD",
    "duration": "forever",
    "max_redemptions": 1,
    "metadata": {
        "merchant_defined": true
    },
    "percent_off": null,
    "redeem_by": 0
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "d776c09c-daa6-453d-8bb3-1af260606d43"
    },
    "data": {
        "id": "coupon_4ab30530e8a7352ffe715deecfab57b9",
        "amount_off": 2,
        "created": 1646825743,
        "currency": "USD",
        "duration": "forever",
        "duration_in_months": 0,
        "max_redemptions": 1,
        "metadata": {
            "merchant_defined": true
        },
        "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
    }
}

In this section:

Documentation

Create Coupon

Parameters

Request Header Parameters

Request Body Parameters

Response Parameters

Code Samples

Search results