Coupons
Give your customers $10 or 10% off their order.
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
}
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
}
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
}
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
}
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
}
]
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
}
]
Last modified 2yr ago