Coupons

Coupons are a type of additional discount that customers can apply to their purchase, and they typically indicate the amount or percentage off. They can be used in a variety of purchase scenarios, such as subscriptions, invoices, checkout sessions, and more. However, it's important to note that coupons cannot be used for one-time charges or payment intents.

Get a list of coupons

Returns a list of your coupons.

GET https://api.partnero.com/v1/coupons

Request parameters

Parameters	Type	Required	Details
limit	integer	no	A limit on the number of items to be returned. Limits can range between 1 and 250, and the default is 15.
page	integer	no	The default is 1.

Response

A list with a data property that contains an array of up to limit coupons. Each entry in the array is a separate coupon object. If no coupons available, the resulting array will be empty. This request should never return an error.

Create a coupon

Coupons come with either a percentage discount or a fixed amount of discount. When a coupon with an amount discount is used, the specified amount is subtracted from the invoice's subtotal. For instance, if an invoice has a subtotal of $100, and a coupon with an amount discount of $200 is applied, the final total will be $0. Similarly, if an invoice has a subtotal of $300, and the coupon with an amount discount of $200 is applied, the final total will be $100.

You may create a coupon via the API using the following example.

POST https://api.partnero.com/v1/coupons

Request example

{
    "name": "PARTNERO25",
    "uuid_code": "",
    "active": true,
    "coupon_discount_type": "percent",
    "coupon_discount_amount": 25,
    "coupon_duration_type": "months",
    "coupon_duration_value": 11,
    "redemption_specific_date_status": false,
    "redemption_specific_date_value": null,
    "redemption_times_status": true,
    "redemption_times_value": 24,
    "promotion_codes": []
}

Request parameters

Parameters	Type	Required	Limitations	Details
name	string	no		Customer facing coupon name. It will be displayed on, for instance invoices, or receipts. If not provided it will be same as uuid_code.
uuid_code	string	no		Identifier of the coupon in the API. We recommend leaving this blank so we can generate an unique uuid code.
active	boolean	yes		Coupon status. If set to false, coupon won't be be available for usage.
coupon_discount_type	string	yes		Determines whether a coupon discounts by a fixed amount or by a percentage.
coupon_discount_amount	float, integer	yes		Based on coupon_discount_type. A positive float larger than 0, and smaller or equal to 100, if percent type is chose, otherwise, a positive integer representing the amount to subtract from an invoice total.
coupon_duration_type	string	yes		This refers to the duration for which the discount will remain valid when applied. Possible values: lifetime, days, months, years
coupon_duration_value	integer, null	based on duration_type		Based on coupon_duaration_type, for days, months and years a positive integer.
redemption_specific_date_status	string	yes		String value, on/off. Indicates if redemption date should be used.
redemption_specific_date_value	date, null	if specific_date_status		Limit the date when customers can redeem the coupon.
redemption_times_status	string	yes		String value, on/of. Indicates if redemption date should be used.
redemption_times_value	integer, null	if redemption_time_status		A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid. For example, you might have a 50% off coupon that the first 20 readers of your blog can use.
promotion_codes	array	no		Optional array of promotion codes. How to define promotion code see promotion code create API.

Response

Returns the coupon object. Response example:

{
    "data": {
        "id": 5,
        "name": "PARTNERO25",
        "uuid_code": "NRKUXAJC",
        "active": true,
        "coupon_discount_type": "percent",
        "coupon_discount_amount": 25,
        "coupon_duration_type": "months",
        "coupon_duration_value": 11,
        "redemption_specific_date_status": false,
        "redemption_specific_date_value": null,
        "redemption_times_status": true,
        "redemption_times_value": 24,
        "promotion_codes": [],
        "created_at": "2023-02-14T12:11:49.000000Z",
        "updated_at": "2023-02-14T12:11:49.000000Z",
        "deleted_at": null
    },
    "status": 1
}

Fetch a coupon

Get the details about specific coupon. You need to provide a coupon uuid_code.

GET https://api.partnero.com/v1/coupons/{uuid_code}

Request example

GET https://api.partnero.com/v1/coupons/NRKUXAJC

Response

Returns a coupon if a valid uuid_code was provided. Otherwise, returns an error. Response example:

{
    "data": {
        "id": 5,
        "name": "PARTNERO25",
        "uuid_code": "NRKUXAJC",
        "active": true,
        "coupon_discount_type": "percent",
        "coupon_discount_amount": 25,
        "coupon_duration_type": "months",
        "coupon_duration_value": 11,
        "redemption_specific_date_status": false,
        "redemption_specific_date_value": null,
        "redemption_times_status": true,
        "redemption_times_value": 24,
        "promotion_codes": [],
        "created_at": "2023-02-14T12:11:49.000000Z",
        "updated_at": "2023-02-14T12:11:49.000000Z",
        "deleted_at": null
    },
    "status": 1
}

Update a coupon

Update an existing coupon.

PUT https://api.partnero.com/v1/coupons

Request example

{
  "id": 5,
  "name": "PARTNERO30",
  "uuid_code": "NRKUXAJC",
  "coupon_discount_type": "percent",
  "coupon_discount_amount": 30,
  "coupon_duration_type": "months",
  "coupon_duration_value": 11,
  "redemption_specific_date_status": false,
  "redemption_specific_date_value": null,
  "redemption_times_status": true,
  "redemption_times_value": 24
}

Request parameters

Parameters	Type	Required	Limitations	Details
id	integer	yes		Id of coupon that's being updated.
name	string	no
uuid_code	string	no
active	string	no
coupon_discount_type	string	no
coupon_discount_amount	float, integer	no
coupon_duration_type	string	no
coupon_duration_value	integer, null	based on duration_type
redemption_specific_date_status	string	no
redemption_specific_date_value	date, null	if specific_date_status
redemption_times_status	string	no
redemption_times_value	integer, null	if redemption_time_status

Note

Promotion codes are not available for updates within coupon update. For updating promotion codes, checkout promotion code update page.

Response

Updated coupon if request succeed. Response example:

{
    "data": {
        "id": 5,
        "name": "PARTNERO25",
        "uuid_code": "NRKUXAJC",
        "active": true,
        "coupon_discount_type": "percent",
        "coupon_discount_amount": 25,
        "coupon_duration_type": "months",
        "coupon_duration_value": 11,
        "redemption_specific_date_status": false,
        "redemption_specific_date_value": null,
        "redemption_times_status": true,
        "redemption_times_value": 24,
        "promotion_codes": [],
        "created_at": "2023-02-14T12:11:49.000000Z",
        "updated_at": "2023-02-14T12:11:49.000000Z",
        "deleted_at": null
    },
    "status": 1
}

Delete a coupon

Delete an existing coupon.

DELETE https://api.partnero.com/v1/coupons

Request example

DELETE https://api.partnero.com/v1/coupons/NRKUXAJC

Response

Status 1 upon success. Otherwise, this call returns a status 0 with "Coupon not found". Response example:

{
    "status": 1
}