Coupon Code

A coupon code is a referral channel code that the authenticated user can apply to their account in order to receive a discount on their subscription. Codes are created by referrers (see Referral Channels); other users redeem them through the endpoints on this page.

At most one coupon code can be in the applied state per user at a time. Applying a new code replaces the previously applied code. Once an applied code is consumed by a paid transaction it moves to the redeemed state and can no longer be applied by the same user.

The applied coupon code object

Attributes	Type	Description
`code`	`string`	The coupon code as configured on the referral channel. `null` when no code is applied.
`promo_type`	`string`	Type of promotion. May be `percent_off` or `value_off`. `null` when no code is applied.
`promo_value`	`decimal`	Magnitude of the promotion. For `percent_off` this is a value between 0 and 1 (e.g. `0.20` for 20% off). For `value_off` this is an absolute USD amount. `null` when no code is applied.
`description`	`string`	Human-readable description configured on the channel. May be an empty string. `null` when no code is applied.
`is_recurring`	`boolean`	If `true`, the discount applies to every renewal while the code remains applied. If `false`, it only applies to the first purchase. `null` when no code is applied.

In JSON format

coupon_code.json

{
  "code": "SUMMER20",
  "promo_type": "percent_off",
  "promo_value": "0.20",
  "description": "20% off the first purchase",
  "is_recurring": false
}

When no code is applied, every field is null:

coupon_code_empty.json

{
  "code": null,
  "promo_type": null,
  "promo_value": null,
  "description": null,
  "is_recurring": null
}

Get applied coupon code

Retrieve the coupon code currently applied to the authenticated user, or an empty object if no code is applied.

Request & Response

GET https://proxy.webshare.io/api/v2/referral/coupon-code/

get_applied_coupon.py

import requests
 
response = requests.get(
    "https://proxy.webshare.io/api/v2/referral/coupon-code/",
    headers={"Authorization": "Token APIKEY"}
)
 
response.json()

The commands above return JSON structured like this:

response.json

{
  "code": "SUMMER20",
  "promo_type": "percent_off",
  "promo_value": "0.20",
  "description": "20% off the first purchase",
  "is_recurring": false
}

Apply a coupon code

Apply a coupon code to the authenticated user. If a code is already applied to the account, it is replaced by the newly submitted one.

This endpoint is rate-limited to 5 requests per minute per user.

Parameters

Parameter	Type	Description
`code`	`string`	The coupon code to apply. Maximum 100 characters. Matching is case-insensitive and surrounding whitespace is trimmed.

Request & Response

POST https://proxy.webshare.io/api/v2/referral/coupon-code/

apply_coupon.py

import requests
 
response = requests.post(
    "https://proxy.webshare.io/api/v2/referral/coupon-code/",
    json={"code": "SUMMER20"},
    headers={"Authorization": "Token APIKEY"}
)
 
response.json()

On success, the response is the applied coupon code object:

response.json

{
  "code": "SUMMER20",
  "promo_type": "percent_off",
  "promo_value": "0.20",
  "description": "20% off the first purchase",
  "is_recurring": false
}

Error responses

When the code cannot be applied, the endpoint returns 400 Bad Request with a validation error of the form {"code": ["<message>"]}. The DRF error code reflects which check failed and can be used to render a localized message client-side.

Error code	Message	Description
`not_found`	`Invalid promo code.`	No matching active referral channel exists, or the channel's `start_date` is in the future.
`code_inactive`	`This code is no longer active.`	The referral channel has been deactivated by its owner.
`code_expired`	`This code has expired.`	The referral channel's `end_date` is in the past.
`self_referral`	`You cannot use your own referral code.`	You attempted to apply a coupon code that you own.
`already_redeemed`	`You have already redeemed this code.`	You have already used this code on a previous paid transaction.

Remove the applied coupon code

Remove the coupon code currently applied to the authenticated user. Already-redeemed codes are not affected.

Request & Response

DELETE https://proxy.webshare.io/api/v2/referral/coupon-code/

remove_coupon.py

import requests
 
response = requests.delete(
    "https://proxy.webshare.io/api/v2/referral/coupon-code/",
    headers={"Authorization": "Token APIKEY"}
)

Returns 204 No Content on success with an empty body.

Referral Channels Referral Info (Public)