Understanding discounts

Discount codes can be applied in various ways, from a single purchase to a recurring subscription.

This guide offers a deeper level of immersion into specific concepts and tasks essential for understanding how to leverage Recharge discounts in your store.

📘
Platform

Shopify Checkout Integration

Migrated Shopify Checkout Integration

Creating discount codes

When creating a discount in the merchant portal, several filters are available to refine and limit its application. See Creating discount codes for detailed instructions.

The following table displays the direct mappings between Merchant Portal UI settings and the parameters you can pass in an API request using Recharge API v. 2021-11.

Number	Merchant portal	Recharge API	Description
1	Type of discount	value_type	The type of discount.
2	Discount code	code	The name of the discount.
3	Applies to	applies_to: resource ids purchase_item_type	The rules that specify how the discount can be applied.
4	Channel Controls	channel_settings	The channels (Merchant Portal, Customer Portal, API) where the discount can be applied.
5	Application limits	usage_limits: first_time_customer_restriction one_application _per_customer	The rules that designate the number of times a discount can be applied and whether discounts can only be applied for new customers.
6	Date Range	starts_at ends_at	The date range for when the discount can be applied.

Detailed discount flow

Discounts can be applied in several different ways, depending on whether you want to apply a discount for a one-time charge or a recurring charge.

Three validations will happen during the life of the discount:

At creation, Recharge checks that all the 'Required' params were specified before creating the discount.
At application, Recharge checks that the checkout respects the rules defined for the checkout or charge this discount is supposed to be applied to.
For recurring charges, Recharge checks whether the discount still applies.

The following flowchart illustrates the step-by-step process of applying a discount to these two workflows.

For more information about discount modeling, refer to Discounts overview .

Async batches for discount creation

🚧
Note:
Async batches are only available in Recharge API version 2021-01. This feature will be coming soon for API version 2021-11.

The Async batches resource can be used for processing large volumes of operations asynchronously, thereby reducing aggregate processing time and network traffic when interacting with many unique objects. For example, a user can leverage this resource to create 1000 discounts with only 3 API requests. Using async batches for discount code creation requires you to perform several steps to accomplish this task.

These steps include:

Creating a batch
Adding a task list to a batch
Processing the batch
Retrieving the batch to verify discount creation

Creating a batch

To create a new batch, you need to make a POST API request to the async_batches endpoint. This request creates a new ID for the batch that you will need to use in subsequent batch operations.

curl --location --request POST 'https://api.rechargeapps.com/async_batches' \
--header 'X-Recharge-Access-Token: {your_access_token} \
--header 'Content-Type: application/json' \
--data-raw '{
   "batch_type": "discount_create"
}'

//Parameters explained
//batch_type - The type of batch created. In this example, discount_create.

import requests
import json

url = "https://api.rechargeapps.com/async_batches"

payload = json.dumps({
 "batch_type": "discount_create"
})
headers = {
 'X-Recharge-Access-Token': {your_access_token},
 'Content-Type': 'application/json',
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("https://api.rechargeapps.com/async_batches")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Recharge-Access-Token"] = "{your_access_token}”
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "batch_type": "discount_create"
})

response = https.request(request)
puts response.read_body

require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.rechargeapps.com/async_batches');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
 'follow_redirects' => TRUE
));
$request->setHeader(array(
 'X-Recharge-Access-Token' => '{your_access_token}',
 'Content-Type' => 'application/json',
));
$request->setBody('{\n  "batch_type": "discount_create"\n}');
try {
 $response = $request->send();
 if ($response->getStatus() == 200) {
   echo $response->getBody();
 }
 else {
   echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
   $response->getReasonPhrase();
 }
}
catch(HTTP_Request2_Exception $e) {
 echo 'Error: ' . $e->getMessage();
}

After you have created the batch, ensure that you copy down the batch_id value. You will need this batch ID to add tasks to a batch and process it. An example of the response with the batch_id is shown below.

Adding a task to a batch

Once you have created the batch, you need to then add a list of tasks you want performed in the batch, with each task representing a single API request. To add tasks to a batch, you need to make a POST request to the async_batches endpoint, with the list of tasks you want to have performed in the body of the request. Be sure to include the batch_id in your request.

🚧
Note:
The following example shows just some of the parameters you can pass in the request body. For a complete list of parameters that can be passed, refer to the Create Discounts endpoint in the Recharge API Reference Guide.

curl --location --request POST 'https://api.rechargeapps.com/async_batches/{batch_id}/tasks' \
--header 'X-Recharge-Access-Token: {your_access_token} \
--header 'Content-Type: application/json' \
--data-raw '{
   "tasks": [
   {
     "body": {
       "code": "indexing",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "maroon",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "web services",
       "value": 100,
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled"
     }
   },
   {
     "body": {
       "code": "PCI",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "Cheese",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "overriding",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "bandwidth-monitored",
       "value": 100,
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled"
     }
   },
   {
     "body": {
       "code": "Falkland Islands (Malvinas)",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "Computer",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "digital",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   }
 ]
}'

//Parameters explained
//code - the name of the discount
//discount_type - the type of discount
//duration - the length of time the discount can be used
//status - the current status of the discount
//value - value of the discount

import requests
import json

url = "https://api.rechargeapps.com/async_batches/{batch_id}/tasks"

payload = json.dumps({
 "tasks": [
   {
     "body": {
       "code": "indexing",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "maroon",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "web services",
       "value": 100,
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled"
     }
   },
   {
     "body": {
       "code": "PCI",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "Cheese",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "overriding",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "bandwidth-monitored",
       "value": 100,
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled"
     }
   },
   {
     "body": {
       "code": "Falkland Islands (Malvinas)",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "Computer",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   },
   {
     "body": {
       "code": "digital",
       "discount_type": "shipping",
       "duration": "forever",
       "status": "enabled",
       "value": 100
     }
   }
 ]
})
headers = {
 'X-Recharge-Access-Token': {your_access_token},
 'Content-Type': 'application/json',
}
response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("https://api.rechargeapps.com/async_batches/763041/tasks")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Recharge-Access-Token"] = "{your_access_token}"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "tasks": [{
      "body": {
        "code": "indexing",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "maroon",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "web services",
        "value": 100,
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled"
      }
    },
    {
      "body": {
        "code": "PCI",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "Cheese",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "overriding",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "bandwidth-monitored",
        "value": 100,
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled"
      }
    },
    {
      "body": {
        "code": "Falkland Islands (Malvinas)",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "Computer",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    },
    {
      "body": {
        "code": "digital",
        "discount_type": "shipping",
        "duration": "forever",
        "status": "enabled",
        "value": 100
      }
    }
  ]
})

response = https.request(request)
puts response.read_body

require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.rechargeapps.com/async_batches/763041/tasks');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
 'follow_redirects' => TRUE
));
$request->setHeader(array(
 'X-Recharge-Access-Token' => '{your_access_token}',
 'Content-Type' => 'application/json',
));
$request->setBody('{\n  "tasks": [\n    {\n      "body": {\n        "code": "indexing",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "maroon",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "web services",\n        "value": 100,\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled"\n      }\n    },\n    {\n      "body": {\n        "code": "PCI",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "Cheese",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "overriding",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "bandwidth-monitored",\n        "value": 100,\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled"\n      }\n    },\n    {\n      "body": {\n        "code": "Falkland Islands (Malvinas)",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "Computer",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    },\n    {\n      "body": {\n        "code": "digital",\n        "discount_type": "shipping",\n        "duration": "forever",\n        "status": "enabled",\n        "value": 100\n      }\n    }\n  ]\n}');
try {
 $response = $request->send();
 if ($response->getStatus() == 200) {
   echo $response->getBody();
 }
 else {
   echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
   $response->getReasonPhrase();
 }
}
catch(HTTP_Request2_Exception $e) {
 echo 'Error: ' . $e->getMessage();
}

Processing the batch

The next step is to process the batch and have it perform the tasks you just added. This requires you to make a POST request to the async_batches endpoint like the following example.

curl --location --request POST 'https://api.rechargeapps.com/async_batches/{batch_id}/process' \
--header 'X-Recharge-Access-Token: {your_access_token} \
--header 'Content-Type: application/json' \
--data-raw '{}'

import requests
import json

url = "https://api.rechargeapps.com/async_batches/batch_id/process"

payload = json.dumps({})
headers = {
 'X-Recharge-Access-Token': {your_access_token},
 'Content-Type': 'application/json',
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("https://api.rechargeapps.com/async_batches/763041/process")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Recharge-Access-Token"] = "{your_access_token}"
request["Content-Type"] = "application/json"
request.body = JSON.dump({})

response = https.request(request)
puts response.read_body

require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.rechargeapps.com/async_batches/763041/process');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
 'follow_redirects' => TRUE
));
$request->setHeader(array(
 'X-Recharge-Access-Token' => '{your_access_token}',
 'Content-Type' => 'application/json',
));
$request->setBody('{}');
try {
 $response = $request->send();
 if ($response->getStatus() == 200) {
   echo $response->getBody();
 }
 else {
   echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
   $response->getReasonPhrase();
 }
}
catch(HTTP_Request2_Exception $e) {
 echo 'Error: ' . $e->getMessage();
}

Retrieving the batch

The final step is to verify that the batch has been created. You can verify the discounts were created by making a GET API request to the async_batches endpoint with the batch_id, similar to the following example.

curl --location --request GET 'https://api.rechargeapps.com/async_batches/{batch_id} \
--header 'X-Recharge-Access-Token: {your_access_token} \

import requests

url = "https://api.rechargeapps.com/async_batches/{batch_id}"

payload={}
headers = {
 'X-Recharge-Access-Token': {your_access_token},
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "net/http"

url = URI("https://api.rechargeapps.com/async_batches/763041")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Recharge-Access-Token"] = "{your_access_token}”

response = https.request(request)
puts response.read_body

require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.rechargeapps.com/async_batches/763041');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
 'follow_redirects' => TRUE
));
$request->setHeader(array(
 'X-Recharge-Access-Token' => '{your_access_token}',
));
try {
 $response = $request->send();
 if ($response->getStatus() == 200) {
   echo $response->getBody();
 }
 else {
   echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
   $response->getReasonPhrase();
 }
}
catch(HTTP_Request2_Exception $e) {
 echo 'Error: ' . $e->getMessage();
}

Discount code sync with other platforms

The discount code sync feature is an efficient tool that enables you to bulk import discount codes from Shopify into Recharge. For more information on how discount code synchronization works, refer to Using the Shopify Discount Import.

This eliminates the manual process of having to create a CSV file and then contacting the Recharge Support team, or building out your own integration. When creating discount codes in bulk, you can click a few buttons in Recharge to import them into Recharge.

When using this feature, be aware of the following conditions:

This is a one-way import from Shopify into Recharge. This feature does not make any updates in Shopify.
Specific discount codes cannot be imported from Shopify. For a list of unsupported discount codes, refer to Using the Shopify Discount Import.
Discount codes cannot be kept in sync automatically because Shopify does not have webhooks available for discounts.
There is a limit of 100,000 discount codes for each import. If you need to import more than 100,000 discount codes, refer to Managing discount codes in bulk.