Discounts

Implement various types of discounts, apply them to customer addresses, and manage discount rules.

Recharge has its own discount engine to allow merchants to offer deals to customers. Discounts can be applied to a checkout, or applied directly to an address. Discounts can also be configured for recurring or single use on subscriptions


Understanding discounts

Some use cases for the Discounts resource include creating discounts, updating the end date for discounts and restricting discounts to first-time customers only.

Discounts can be used in combination with webhooks to trigger a discount when customers meet certain order criteria. This method allows you to introduce more complex applications of discounts depending on your customer's needs.

The following table details which scopes are required when using the discounts record.

ScopeDescription
read_discountsRequired to retrieve a discount.
write_discountsRequired to write to the discounts record.
write_addressesOnly required to apply discounts to an address.
write_ordersOnly required to apply discount to charge.

Discounts Flow Chart

The following flowchart allows you to visualize how discounts work in Recharge.



Applying a discount to an address

You can directly apply a discount to an address:

POST to /addresses/:id/apply_discount

Addresses can only have one discount applied and you cannot apply a discount if an existing queued charge in the address already has a discount.


Applying a discount to a charge

Add a discount directly to a charge:

POST to /charges/:id/apply_discount

You cannot add another discount to an existing queued charge if the charge already has a discount. You can provide either the discount_id or discount_code. If you pass both parameters, the discount_id value will override the value in discount_code.

🚧

Note:

Regeneration is a process that refreshes the charge JSON with new data when a subscription or address is updated. If a charge has a discount and it gets updated or a regeneration occurs, the discount will be lost.


Create a free shipping discount

Free shipping is often used to encourage customer to group their purchase which increases AOV and makes it affordable for a merchant to offer free Shipping. It is also often used as a reward mechanic for loyalty or an incentive to encourage a prospective customer to try something new.

When creating a free shipping discount you need to consider the following inputs:

  • What name do we want to give the discount?
  • How long will this discount apply for every customer?
    Your options are "single use", "usage limit" (more than once but not forever) and "forever". Typically single use will be offered on initial purchase incentive, usage limit will be often for special offers or specific products and forever is commonly to reward loyalty.
  • Will the discount be available for a limited amount of time? how long for?
  • Will this offer be limited in number of users? e.g. free Shipping for the 1st 100 users.
  • Will you want to allow a customer to apply the discount to multiple addresses.
  • Will you want to restrict the free shipping to certain products or collection of products or type of subscription?

Once you have all those elements decided you can go ahead and create the free shipping discount code with the below required parameters at minima. You can find more parameters in the API Reference.

AttributeInstruction
applies_to_idMust be set to null for free shipping.
applies_to_product_typeMust be set to null for free shipping.
codeName of the discount code.
discount_typeMust be set to shipping for free shipping.
durationBased on what you decided with the team you must pick one of the below values:
forever - will always apply to the Address the customer choses to apply it to
usage_limit - if you want to set a finite number of charges (>1) the discount will apply for
single_use - it will apply only once
duration_usage_limit If you chose usage_limit for the duration
end_atUse if you want the discount to be valid for application by the customer for a limited time.
Note - this only valid for the application of the discount. If applied during the correct time window specified the discount will then act according to your definition of duration
once_per_customerSet to 1 if you want to restrict the application to one address per customer.
starts_atThe date after which the discount will become active.
usage_limitUse if you want to limit the number of customers allowed to apply the discount
valueMust be set to 100 for free shipping

POST /discounts

curl https://api.rechargeapps.com/discounts \
-H 'Content-Type: application/json' \
-H 'X-Recharge-Access-Token: your_api_token' \
-d '{
  "channel_settings": {
    "api": {
      "can_apply": false
    },
    "checkout_page": {
      "can_apply": true
    },
    "customer_portal": {
      "can_apply": true
    },
    "merchant_portal": {
      "can_apply": false
    }
  },
  "code": "Example",
  "discount_type": "shipping",
  "duration": "usage_limit",
  "duration_usage_limit": 5,
  "starts_at": "2019-09-05",
  "usage_limit": 1,
  "value": 100
}'
import requests
import json

headers = {
  "Content-Type": "application/json",
  "X-Recharge-Access-Token": "your_api_token"
}
url = "https://api.rechargeapps.com/discounts"
data = {
  "channel_settings": {
    "api": {
        "can_apply": False
    },
    "checkout_page": {
        "can_apply": True
    },
    "customer_portal": {
        "can_apply": True
    },
    "merchant_portal": {
        "can_apply": False
    }
  },
  "code": "Example",
  "discount_type": "shipping",
  "duration": "usage_limit",
  "duration_usage_limit": 5,
  "starts_at": "2019-09-05",
  "usage_limit": 1,
  "value": 100
}

result = requests.post(url, json.dumps(data), headers=headers)
print(json.dumps(json.loads(result.text), indent=2))
$request = new HttpRequest();
$request->setUrl('https://api.rechargeapps.com/discounts');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'X-Recharge-Access-Token' => 'your_api_token'
));
$request->setBody('{
  "channel_settings": {
    "api": {
      "can_apply": false
    },
    "checkout_page": {
      "can_apply": true
    },
    "customer_portal": {
      "can_apply": true
    },
    "merchant_portal": {
      "can_apply": false
    }
  },
  "code": "Example",
  "discount_type": "shipping",
  "duration": "usage_limit",
  "duration_usage_limit": 5,
  "starts_at": "2019-09-05",
  "usage_limit": 1,
  "value": 100
}');

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
require 'net/http'
require 'uri'
require 'json'

url = URI("https://api.rechargeapps.com/discounts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["X-Recharge-Access-Token"] = 'your_api_token'
request.body = {
  "channel_settings": {
    "api": {
      "can_apply": false
    },
    "checkout_page": {
      "can_apply": true
    },
    "customer_portal": {
      "can_apply": true
    },
    "merchant_portal": {
      "can_apply": false
    }
  },
  "code": "Example",
  "discount_type": "shipping",
  "duration": "usage_limit",
  "duration_usage_limit": 5,
  "starts_at": "2019-09-05",
  "usage_limit": 1,
  "value": 100
}.to_json

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

Need Help? Contact Us