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 |
|
| The name of the Coupon, e.g., Summer 2019. |
|
| 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. |
|
| 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%. |
|
| The amount off the price of the order given by the Coupon. |
|
| Defines when a Coupon will become available for your customer. By default it's defined as the moment you create it. |
|
| The Coupon will not be usable by your customer after this date. |
|
| If it's defined, then the Coupon will be only usable n times. |
|
| 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 currency
field must be set when using amount_off
.
Body parameter | Type | Description |
|
| The name of a Coupon, e.g., Summer 2019 |
|
| 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. |
|
| 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%. |
|
| The amount off the price of the order given by the Coupon. |
|
| Defines when a coupon is gonna be available for your customer. By default it's defined as the moment you create it. |
|
| The coupon will not be usable by your customer after this date. |
|
| If it's defined, then the Coupon will be only usable n times. |
POST /coupons HTTP/1.1Content-Type: application/jsonX-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 OKContent-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
.
Path Parameters | Type | Description |
|
| ID of the queried coupon. |
Body Parameters | Type | Description |
|
| The name of a Coupon, e.g., Summer 2019. |
|
| 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. |
|
| 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%. |
|
| The amount off the price of the order given by the Coupon. |
|
| Defines when a coupon is gonna be available for your customer. By default it's defined as the moment you create it. |
|
| The coupon will not be usable by your customer after this date. |
|
| If it's defined, then the Coupon will be only usable n times. |
PUT /coupons/<coupon_id> HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"percent_off": 0.25}
HTTP/1.1 200 OKContent-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}
Path Parameters | Type | Description |
|
| ID of the queried Coupon. |
DELETE /coupons/<coupon_id> HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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}
Path Parameters | Type | Description |
|
| The Coupon's ID. |
GET /coupons/<coupon_id> HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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}
Query Parameters | Type | Description |
|
| Number of items to retrieve. Default is 10. |
|
| Which page to retrieve. Default is 0. |
|
| Date field used to filter results. Default is |
|
| Start date, |
|
| End date, |
|
| Field used for sorting results. Default is by |
|
| Also retrieves the deleted ones. Default is |
|
| Retrieves items in a specific active status. Default is |
GET /coupons HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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}]
Query Parameters | Type | Description |
|
| The search query; code, name or id. |
|
| Number of items to retrieve. Default is 10. |
|
| Which page to retrieve. Default is 0. |
|
| Date field used to filter results. Default is |
|
| Start date, |
|
| End date, |
|
| Field used for sorting results. Default is by |
|
| Also retrieves the deleted ones. Default is |
|
| Retrieves items in a specific active status.Default is |
GET /coupons/search HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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}]