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

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.

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.

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.

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
}
]