Discounts

Discounts are a powerful tool in Mercantive to attract customers and boost sales — they allow you to offer special pricing on your products. On this page, we'll dive into the different discount endpoints you can use to manage discounts programmatically. We'll look at how to query, create, update, and delete discounts.

The discount model

The discount model contains all the information about your discounts, including the discount code, amount, type, duration, and which products it applies to. It also includes details about when the discount is valid and how many times it can be used.

Properties

Name
id
Type
uuid
Description
Unique identifier for the discount.
Name
store_id
Type
uuid
Description
Unique identifier for the store this discount belongs to.
Name
name
Type
string
Description
The name of the discount.
Name
code
Type
string
Description
The code customers use to apply this discount.
Name
published
Type
boolean
Description
Indicates whether the discount is published or not.
Name
type
Type
string
Description
The type of discount: PERCENTAGE or FIXED.
Name
amount
Type
number
Description
The amount of the discount.
Name
starts_at
Type
string | null
Description
The start date and time of the discount's validity period.
Name
ends_at
Type
string | null
Description
The end date and time of the discount's validity period.
Name
max_redemptions
Type
number | null
Description
The maximum number of times this discount can be redeemed.
Name
duration
Type
string
Description
The duration type of the discount: ONCE, REPEATING, or FOREVER.
Name
duration_in_months
Type
number | null
Description
The number of months the discount is valid for, if the duration is REPEATING.
Name
total_formatted
Type
string
Description
A formatted string representation of the discount amount.
Name
status
Type
string
Description
The current status of the discount.
Name
products
Type
array
Description
An array of product objects this discount applies to.
Name
created_at
Type
string
Description
Timestamp of when the discount was created.
Name
updated_at
Type
string
Description
Timestamp of when the discount was last updated.

GET/discounts

List all discounts

This endpoint allows you to retrieve a paginated list of all your discounts.

Optional attributes

Name
page
Type
integer
Description
The page number to retrieve.

Request

GET

/discounts

curl -X GET https://api.mercantive.com/v1/discounts \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": "9d1c7704-c3a2-471e-b384-6728e310df95",
      "store_id": "9d1c7340-edfd-4d51-a4e1-381da586408a",
      "name": "BLACK FRIDAY",
      "code": "BLACKFRIDAY",
      "published": false,
      "type": "PERCENTAGE",
      "amount": 50,
      "starts_at": null,
      "ends_at": null,
      "max_redemptions": null,
      "duration": "ONCE",
      "duration_in_months": null,
      "total_formatted": "50%",
      "status": "Active",
      "products": [
        {
          "id": "9d1c7390-1eb7-4dd7-a433-442c9ecf9224",
          "store_id": "9d1c7340-edfd-4d51-a4e1-381da586408a",
          "name": "eBook",
          "description": "A great book.",
          "slug": "zwAToRm",
          "published": true,
          "display_on_storefront": true,
          "type": "EBOOK",
          "email_receipt_button_text": null,
          "email_receipt_button_link": null,
          "email_receipt_message": null,
          "archived": false,
          "created_at": "2024-09-27T16:40:34.000000Z",
          "updated_at": "2024-09-27T16:41:16.000000Z"
        }
      ],
      "created_at": "2024-09-27T16:50:14.000000Z",
      "updated_at": "2024-09-27T16:50:19.000000Z"
    }
  ],
  "links": {
    "first": "https://api.mercantive.com/v1/discounts?page=1",
    "last": "https://api.mercantive.com/v1/discounts?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "Previous",
        "active": false
      },
      {
        "url": "https://api.mercantive.com/v1/discounts?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next",
        "active": false
      }
    ],
    "path": "https://api.mercantive.com/v1/discounts",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}