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.

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

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.

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

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.

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

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

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

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

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