Partnero Developers

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

ParametersTypeRequiredDetails
limitintegernoA limit on the number of items to be returned. Limits can range between 1 and 250, and the default is 15.
pageintegernoThe 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": {},
    "metadata": {}
}

Request parameters

ParametersTypeRequiredLimitationsDetails
namestringnoCustomer facing coupon name. It will be displayed on, for instance invoices, or receipts. If not provided it will be same as uuid_code.
uuid_codestringnoIdentifier of the coupon in the API. We recommend leaving this blank so we can generate an unique uuid code.
activebooleanyesCoupon status. If set to false, coupon won't be be available for usage.
coupon_discount_typestringyesDetermines whether a coupon discounts by a fixed amount or by a percentage.
coupon_discount_amountfloat, integeryesBased 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_typestringyesThis refers to the duration for which the discount will remain valid when applied. Possible values: lifetime, days, months, years
coupon_duration_valueinteger, nullbased on duration_typeBased on coupon_duaration_type, for days, months and years a positive integer.
redemption_specific_date_statusstringyesString value, on/off. Indicates if redemption date should be used.
redemption_specific_date_valuedate, nullif specific_date_statusLimit the date when customers can redeem the coupon.
redemption_times_statusstringyesString value, on/of. Indicates if redemption date should be used.
redemption_times_valueinteger, nullif redemption_time_statusA 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_codesarraynoOptional array of promotion codes. How to define promotion code see promotion code create API.
metadataobjectnoObject of Key value pairs.

Response

Returns the coupon object.

Response example:

{
    "data": {
        "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": {},
        "metadata": {},
        "created_at": "2023-02-14T12:11:49.000000Z",
        "updated_at": "2023-02-14T12:11:49.000000Z",
        "deleted_at": null
    },
    "status": 1,
    "message": "Coupon created in the app successfully.",
    "synchronization_enabled": false,
    "synchronization_successful": false,
    "synchronization_message": ""
}

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": {
        "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": {},
        "metadata": {},
        "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

{
  "name": "PARTNERO30",
  "uuid_code": "NRKUXAJC",
  "metadata": {}
}

Request parameters

ParametersTypeRequiredLimitationsDetails
namestringnoNew name
uuid_codestringyesUuid code of coupon that's being updated.
metadataobjectnoObject of Key value pairs

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": {
        "name": "PARTNERO30",
        "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": {},
        "metadata": {},
        "created_at": "2023-02-14T12:11:49.000000Z",
        "updated_at": "2023-02-14T12:11:49.000000Z",
        "deleted_at": null
    },
    "status": 1,
    "message": "Coupon updated in the app successfully.",
    "synchronization_enabled": false,
    "synchronization_successful": false,
    "synchronization_message": ""
}

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:

{
  "data": {
     "status": 1,
     "message": "Coupon deleted in the app successfully.",
     "synchronization_enabled": false,
     "synchronization_successful": false,
     "synchronization_message": ""
  }
}