Coupons

Coupon Object
Our coupons allow you to give your customers either a fixed amount or a particular percentage off their order. You can define when you want the coupon to be valid and how many times you want it to be able to be used.
Attribute
Type
Description
name
string
The name of the Coupon, e.g., Summer 2019.
code
string
The code for the Coupon. This could be used by your customer while creating an Order, e.g, SUM2019.
If the code is not defined, it will be given a 'human readable' code of 6 randomly generated characters.
percent_off
float
The percentage of discount on the order given by the Coupon as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
amount_off
float
The amount off the price of the order given by the Coupon.
starting_date
object
Defines when a Coupon will become available for your customer. By default it's defined as the moment you create it.
ending_date
object
The Coupon will not be usable by your customer after this date.
max_redemptions
number
If it's defined, then the Coupon will be only usable n times.
used_count
number
The number of times the Coupon has been used.
The Coupon Object has two closely related fields, or types: percentage_off and amount_off . Only one can be defined while creating a new Coupon.
If you want to offer your customers a percentage off their total purchase as a discount, set the percentage_off to your desired percentage. Alternatively, set the amount_off for a fixed amount to be deducted from their total amount. Note: the currencyfield must be set when using amount_off.
Parameters
Request
Response
Body parameter
Type
Description
name
string
The name of a Coupon, e.g., Summer 2019
code
string
The code of a Coupon. This could be used by your customer while creating an Order, e.g, SUM2019.
If the code is not defined, it will be given a 'human readable' code of 6 randomly generated characters.
percent_off
float
The percentage of discount on the order given by the Coupon as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
amount_off
float
The amount off the price of the order given by the Coupon.
starting_date
number
Defines when a coupon is gonna be available for your customer. By default it's defined as the moment you create it.
ending_date
number
The coupon will not be usable by your customer after this date.
max_redemptions
number
If it's defined, then the Coupon will be only usable n times.
POST /coupons HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "name": "The Summer 2019",
    "code": "SUM2019",
    "amount_off": 20,
    "currency": "EUR",
    "starting_date": 1561967337,
    "ending_date": 1567299599,
    "max_redemptions": 10000    
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "_id": {
        "$oid": "5931697ed57ba271c0c7fr42"},
    "created": {
        "$date": 1496410494652},
    "modified": {
        "$date": 1496410494652},
    "company": {
        "$oid": "57ee9c71d76d431f8511142f"},
    "active": true,
    "delete": false,
    "name": "The Summer 2019",
    "code": "SUM2019",
    "amount_off": 20,
    "currency": "EUR",
    "starting_date": {"$date": 1561967337},
    "ending_date": {"$date": 1567299599},
    "max_redemptions": 10000,
    "used_count": 0 
}
Update a Coupon
If you decide to change the type of a Coupon, it's very simple: you just have to define the other type, percentage_off or amount_off, and BuiltOn removes the original field.
Remember, amount_off always requires that you set currency.
Parameters
Request
Response
Path Parameters
Type
Description
coupon_id
string
ID of the queried coupon.
Body Parameters
Type
Description
name
string
The name of a Coupon, e.g., Summer 2019.
code
string
The code of a Coupon. This could be used by your customer while creating an Order, e.g, SUM2019.
If the code is not defined, it will be given a 'human readable' code of 6 randomly generated characters.
percent_off
float
The percentage of discount on the order given by the Coupon as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
amount_off
float
The amount off the price of the order given by the Coupon.
starting_date
number
Defines when a coupon is gonna be available for your customer. By default it's defined as the moment you create it.
ending_date
number
The coupon will not be usable by your customer after this date.
max_redemptions
number
If it's defined, then the Coupon will be only usable n times.
PUT /coupons/<coupon_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "percent_off": 0.25  
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "_id": {
        "$oid": "5931697ed57ba271c0c7fr42"},
    "created": {
        "$date": 1496410494652},
    "modified": {
        "$date": 1496410494652},
    "company": {
        "$oid": "57ee9c71d76d431f8511142f"},
    "active": true,
    "delete": false,
    "name": "The Summer 2019",
    "code": "SUM2019",
    "percent_off": 0.25,
    "currency": "EUR",
    "starting_date": {"$date": 1561967337},
    "ending_date": {"$date": 1567299599},
    "max_redemptions": 10000,
    "used_count": 0 
}
Delete a Coupon
Parameters
Request
Response
Path Parameters
Type
Description
coupon_id
string
ID of the queried Coupon.
DELETE /coupons/<coupon_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "_id": {
        "$oid": "5931697ed57ba271c0c7fr42"},
    "created": {
        "$date": 1496410494652},
    "modified": {
        "$date": 1496410494652},
    "company": {
        "$oid": "57ee9c71d76d431f8511142f"},
    "active": false,
    "delete": true,
    "name": "The Summer 2019",
    "code": "SUM2019",
    "percent_off": 0.25,
    "currency": "EUR",
    "starting_date": {"$date": 1561967337},
    "ending_date": {"$date": 1567299599},
    "max_redemptions": 10000,
    "used_count": 0 
}
Retrieve a Coupon
Parameters
Request
Response
Path Parameters
Type
Description
coupon_id
string
The Coupon's ID.
GET /coupons/<coupon_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "_id": {
        "$oid": "5931697ed57ba271c0c7fr42"},
    "created": {
        "$date": 1496410494652},
    "modified": {
        "$date": 1496410494652},
    "company": {
        "$oid": "57ee9c71d76d431f8511142f"},
    "active": true,
    "delete": false,
    "name": "The Summer 2019",
    "code": "SUM2019",
    "percent_off": 0.25,
    "currency": "EUR",
    "starting_fate": {"$date": 1561967337},
    "ending_date": {"$date": 1567299599},
    "max_redemptions": 10000,
    "used_count": 0 
}
Get a list of Coupons
Parameters
Request
Response
Query Parameters
Type
Description
size
number
Number of items to retrieve. Default is 10.
page
number
Which page to retrieve. Default is 0.
date_filter
number
Date field used to filter results. Default is CREATED.
from_date
number
Start date, timestamp format. Default is None.
to_date
number
End date, timestamp format. Default is None.
sort
string
Field used for sorting results. Default is by name.
included_deleted
boolean
Also retrieves the deleted ones. Default is False.
active
boolean
Retrieves items in a specific active status. Default is None.
GET /coupons HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
[
    {
        "_id": {
            "$oid": "5931697ed57ba271c0c7fr42"},
        "created": {
            "$date": 1496410494652},
        "modified": {
            "$date": 1496410494652},
        "company": {
            "$oid": "57ee9c71d76d431f8511142f"},
        "active": true,
        "delete": false,
        "name": "The Summer 2019",
        "code": "SUM2019",
        "percent_off": 0.25,
        "currency": "EUR",
        "starting_date": {"$date": 1561967337},
        "ending_date": {"$date": 1567299599},
        "max_redemptions": 10000,
        "used_count": 0 
    }
]
Search Coupons
Parameters
Request
Response
Query Parameters
Type
Description
query
string
The search query; code, name or id.
size
number
Number of items to retrieve. Default is 10.
page
number
Which page to retrieve. Default is 0.
date_filter
number
Date field used to filter results. Default is CREATED.
from_date
number
Start date, timestamp format. Default is None.
to_date
number
End date, timestamp format. Default is None.
sort
string
Field used for sorting results. Default is by name.
included_deleted
boolean
Also retrieves the deleted ones. Default is False.
active
boolean
Retrieves items in a specific active status.Default is None.
GET /coupons/search HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
[
    {
        "_id": {
            "$oid": "5931697ed57ba271c0c7fr42"},
        "created": {
            "$date": 1496410494652},
        "modified": {
            "$date": 1496410494652},
        "company": {
            "$oid": "57ee9c71d76d431f8511142f"},
        "active": true,
        "delete": false,
        "name": "The Summer 2019",
        "code": "SUM2019",
        "percent_off": 0.25,
        "currency": "EUR",
        "starting_date": {"$date": 1561967337},
        "ending_date": {"$date": 1567299599},
        "max_redemptions": 10000,
        "used_count": 0 
    }
]
Building Blocks - Previous
Orders
Next - Building Blocks
Subscriptions and Plans
Last modified 2yr ago
Copy link
On this page
Coupon Object
Update a Coupon
Delete a Coupon
Retrieve a Coupon
Get a list of Coupons
Search Coupons