Coupons

Give your customers $10 or 10% off their order.

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.
currency
string
Three letter currency code in standard ISO 4217 format.  This is required if you're using amount_off. 
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.
Create a Coupon
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
Parameters
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.
currency
string
Three letter currency code in standard ISO 4217 format. This is required if you're using amount_off.
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.
Request
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    
}
Response
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
Parameters
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.
currency
string
Three letter currency code in standard ISO 4217 format. This is required if you're using amount_off.
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.
Request
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  
}
Response
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
Parameters
Path Parameters
Type
Description
coupon_id
string
ID of the queried Coupon.
Request
DELETE /coupons/<coupon_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
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
Parameters
Path Parameters
Type
Description
coupon_id
string
The Coupon's ID.
Request
GET /coupons/<coupon_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
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
Parameters
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. 
Request
GET /coupons HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
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
Parameters
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.
Request
GET /coupons/search HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
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 updated 4 months ago

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.
`currency`	`string`	Three letter currency code in standard ISO 4217 format. This is required if you're using `amount_off`.
`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.

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.
`currency`	`string`	Three letter currency code in standard ISO 4217 format. This is required if you're using `amount_off`.
`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.

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.
`currency`	`string`	Three letter currency code in standard ISO 4217 format. This is required if you're using `amount_off`.
`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.

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

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

Path Parameters	Type	Description
`coupon_id`	`string`	ID of the queried coupon.