Skip to main content

Promotion

Version: 1.0

You can use the Promotion resource to create a promotion.

Authenticated access scopes: com.read_discounts, com.write_discounts (Only used by the private app)

What you can do with Promotion​

The Haravan API lets you do the following with the Promotion resource.

Properties​

name: string

"name": "Happy new year"

Name of the promotion.

ends_at: string

"ends_at": "2022-08-11T09:35:59Z"

The date and time (ISO 8601 format) when the promotion was expired.

id: number

"id": 1206854680

A unique identifier for the promotion.

starts_at: string

"starts_at": "2021-05-13T07:29:20.1Z"

The date and time (ISO 8601 format) when the promotion was applied.

discount_type: string

"discount_type": "fixed_amount"

  • fixed_amount: Applies a discount of value as a unit of the store's currency.

  • percentage: Applies a percentage discount of value.

  • same_price: Same price.

value: number

"value ": 150000

Promotion value depend on "discount_type".

If discount_type is "percentage". The value will be percent.

applies_to_resource: string

"applies_to_resource": "product"
  • null: Apply to all orders.
  • product: Apply to the product.
  • collection: Apply to the collection.
  • product_variant: Apply to product variants.

applies_to_quantity: number

"applies_to_quantity":2

Minimum quantity of items to be applied promotion.

applies_to_id: number

"applies_to_id":0

The ID of the product to be applied promotion.

order_over: number

"order_over":100000

Minimum purchase amount to be applied promotion.

promotion_apply_type: number

"promotion_apply_type":1

  • 1: Minimum quantity of items.

  • 2: Minimum purchase amount.

variants: array

"variants": [

    {

        "product_id": 1028183633,

        "variant_id": 1061514629

    },

    {

        "product_id": 1028183633,

        "variant_id": 1061514630

    }

]

Array to product ids and variant id objects to which the promotion will be applied.

created_at: string

"created_at": "2021-05-13T07:29:20.1Z"

The date and time (ISO 8601 format) when the promotion was created.

updated_at: string

"updated_at": "2021-05-13T07:29:20.808Z"

The date and time (ISO 8601 format) when the promotion was last updated.

first_name: string

"first_name":"John"

The first name of the user created the promotion.

last_name: string

"last_name":"Smit"

The last name of the user created the promotion.

create_user: number

"create_user":200000493247

The ID of the user-created the promotion.

status: string

"status":"enabled"

Status of the promotion. Values are valid:

  • enabled: The promotion is active.
  • disabled: The promotion is disabled.

Applicable products

products_selection : string

"products_selection" : "all"
  • all : All
  • collection_prerequisite : Prerequisite collection
  • variant_prerequisite : Prerequisite variant
  • product_prerequisite : Prerequisite product

Applicable customer

customers_selection : string

"customers_selection" : "all"
  • all : All
  • customersegment_prerequisite : Prerequisite customer segment
  • customer_prerequisite : Prerequisite customer

Applicable shipping location

provinces_selection : string

"provinces_selection" : "all"
  • all: All
  • province_prerequisite: Prerequisite province

Applicable channels

channels_selection : string

"channels_selection" : "all"
  • all: All
  • channel_prerequisite: Prerequisite channel

Applicable locations

locations_selection : string

"locations_selection" : "all"
  • all: All
  • location_prerequisite Prerequisite location

Applicable collections

entitled_collection_ids : array

"entitled_collection_ids" : [1004145086, 1004145085, 1004145084]
  • entitled_collection_ids: Entitled collection

Applicable products

entitled_product_ids : array

"entitled_product_ids" : [1055262740, 1055262741, 1055262730]
  • entitled_product_ids: Entitled product ids

Applicable variants

entitled_variant_ids : array

"entitled_variant_ids" : [1124400234, 1124400235, 1124400233]
  • entitled_variant_ids: Entitled variant ids

Applicable customers

entitled_customer_ids : array

"entitled_customer_ids" : [1128891111]
  • entitled_customer_ids: Entitled customer ids

Customer eligibility

entitled_customer_segment_ids : array

"entitled_customer_segment_ids" : [73624622, 73624623, 73624624]
  • entitled_customer_segment_ids: Entitled custoemr segment ids

Applicable shipping location

entitled_province_ids : array

"entitled_province_ids" : [50, 32, 57]
  • entitled_province_ids: Entitled province ids

Applicable channels

entitled_channels : array

"entitled_channels" : ["pos", "web", "harasocial"]
  • entitled_channels: Entitled channels

Applicable locations

entitled_location_ids : array

"entitled_location_ids" : [1690961]
  • entitled_location_ids: Entitled location ids

Rule customs

rule_customs : array

"rule_customs" : [
    {
      "name": "customer_limit_used", 
      "value": "5"
    },
    {
      "name": "time_range",
      "value": "[{\"name\":\"monday\",\"value_range\":[]},{\"name\":\"tuesday\",\"value_range\":[]},{\"name\":\"wednesday\",\"value_range\":[[\"1:00\",\"1:30\"]]},{\"name\":\"thursday\",\"value_range\":[]}]"
    },
    {
      "name": "shipping_max_apply_value",
      "value": "100"
    }
]
  • customer_limit_used: Limit to one use per customer
  • time_range: Active dates
  • shipping_max_apply_value: Shipping max

Discount type

take_type : string

"take_type" : "fixed_amount"
  • fixed_amount : Fixed amount
  • percentage : Percentage

Usage limits

usage_limit : number

"usage_limit" : 10
  • usage_limit: Limit number of times this discount can be used in total

Endpoints​

Retrieves a list of enabling promotions​

GET
https://apis.haravan.com/com/promotions.json

Parameters​

limit

Limit of the result.

page

Page to show the result.

since_id

Restrict results to after the specified ID.

code

Filter result by the code.

Retrieves a list of enabling discount codes by page number.

By default, the number of resources on the page is 50.

  • GET https://apis.haravan.com/com/promotions.json?page=1
Details
HTTP/1.1 200 OK
{
    "promotions": [
        {
            "name": "Happy new year",
            "ends_at": "2022-03-04T16:59:59Z",
            "id": 1024173229,
            "starts_at": "2022-03-04T03:54:00Z",
            "value": 10000.0000,
            "discount_type": "fixed_amount",
            "applies_to_resource": "product_variant",
            "applies_to_quantity": 0,
            "applies_to_id": 0,
            "set_time_active": false,
            "order_over": 1000000,
            "promotion_apply_type": 2,
            "variants": [
                {
                    "product_id": 1028183633,
                    "variant_id": 1061514629
                },
                {
                    "product_id": 1028183633,
                    "variant_id": 1061514630
                }
            ],
            "created_at": "2022-03-04T03:56:37.215Z",
            "updated_at": "2022-03-04T03:56:37.215Z",
            "first_name": null,
            "last_name": null,
            "create_user": 200000493247,
            "applies_customer_group_id": null,
            "status": "enabled",
            "products_selection": "collection_prerequisite",
            "customers_selection": "customersegment_prerequisite",
            "provinces_selection": "all",
            "channels_selection": "channel_prerequisite",
            "locations_selection": "location_prerequisite",
            "entitled_collection_ids": [
                1004145086,
                1004145085,
                1004145084
            ],
            "entitled_product_ids": [],
            "entitled_variant_ids": [],
            "entitled_customer_ids": [],
            "entitled_customer_segment_ids": [
                73624622,
                73624623,
                73624613,
                73624621,
                73624624
            ],
            "entitled_province_ids": [],
            "entitled_channels": [
                "pos",
                "web",
                "harasocial"
            ],
            "entitled_location_ids": [
                1690961
            ],
            "rule_customs": [],
            "take_type": "percentage",
            "usage_limit": 10            
        },
        {
            "name": "Vallentine",
            "ends_at": "2022-08-11T09:35:59Z",
            "id": 1022775866,
            "starts_at": "2021-08-11T08:35:00Z",
            "value": 10.0000,
            "discount_type": "percentage",
            "applies_to_resource": "product",
            "applies_to_quantity": 1,
            "applies_to_id": 1028183633,
            "set_time_active": false,
            "order_over": null,
            "promotion_apply_type": 1,
            "variants": [],
            "created_at": "2022-01-25T12:07:59.374Z",
            "updated_at": "2022-01-25T12:07:59.374Z",
            "first_name": null,
            "last_name": null,
            "create_user": 200000497867,
            "applies_customer_group_id": null,
            "status": "enabled",
            "products_selection": "collection_prerequisite",
            "customers_selection": "customersegment_prerequisite",
            "provinces_selection": "all",
            "channels_selection": "channel_prerequisite",
            "locations_selection": "location_prerequisite",
            "entitled_collection_ids": [
                1004145086,
                1004145085,
                1004145084
            ],
            "entitled_product_ids": [],
            "entitled_variant_ids": [],
            "entitled_customer_ids": [],
            "entitled_customer_segment_ids": [
                73624622,
                73624623,
                73624613,
                73624621,
                73624624
            ],
            "entitled_province_ids": [],
            "entitled_channels": [
                "pos",
                "web",
                "harasocial"
            ],
            "entitled_location_ids": [
                1690961
            ],
            "rule_customs": [],
            "take_type": "percentage",
            "usage_limit": 10
        }
    ]
}

Retrieves single the promotion​

GET
https://apis.haravan.com/com/promotions/{promotion_id}.json

Retrieves single the discount code.

  • GET https://apis.haravan.com/com/promotions/1024173229.json
Details
HTTP/1.1 200 OK
{
    "promotion": {
        "name": "Happy new year",
        "ends_at": "2022-03-04T16:59:59Z",
        "id": 1024173229,
        "starts_at": "2022-03-04T03:54:00Z",
        "value": 10000.0000,
        "discount_type": "fixed_amount",
        "applies_to_resource": "product_variant",
        "applies_to_quantity": 0,
        "applies_to_id": 0,
        "set_time_active": false,
        "order_over": 1000000,
        "promotion_apply_type": 2,
        "variants": [
            {
                "product_id": 1028183633,
                "variant_id": 1061514629
            },
            {
                "product_id": 1028183633,
                "variant_id": 1061514630
            }
        ],
        "created_at": "2022-03-04T03:56:37.215Z",
        "updated_at": "2022-03-04T03:56:37.215Z",
        "first_name": null,
        "last_name": null,
        "create_user": 200000493247,
        "applies_customer_group_id": null,
        "status": "enabled",
        "products_selection": "collection_prerequisite",
        "customers_selection": "customersegment_prerequisite",
        "provinces_selection": "all",
        "channels_selection": "channel_prerequisite",
        "locations_selection": "location_prerequisite",
        "entitled_collection_ids": [
            1004145086,
            1004145085,
            1004145084
        ],
        "entitled_product_ids": [],
        "entitled_variant_ids": [],
        "entitled_customer_ids": [],
        "entitled_customer_segment_ids": [
            73624622,
            73624623,
            73624613,
            73624621,
            73624624
        ],
        "entitled_province_ids": [],
        "entitled_channels": [
            "pos",
            "web",
            "harasocial"
        ],
        "entitled_location_ids": [
            1690961
        ],
        "rule_customs": [],
        "take_type": "percentage",
        "usage_limit": 10
    }
}

Create a promotion​

POST
https://apis.haravan.com/com/promotions.json

Create a promotion.

  • POST https://apis.haravan.com/com/promotions.json
{
    "promotion": 
        {
            "name": "Happy new year",
            "ends_at": "2022-03-04T16:59:59Z",
            "id": 1024173229,
            "starts_at": "2022-03-04T03:54:00Z",
            "value": 10000.0000,
            "discount_type": "fixed_amount",
            "applies_to_resource": "product_variant",
            "applies_to_quantity": 0,
            "applies_to_id": 0,
            "order_over": 1000000,
            "promotion_apply_type": 2,
            "variants": [
                {
                    "product_id": 1028183633,
                    "variant_id": 1061514629
                },
                {
                    "product_id": 1028183633,
                    "variant_id": 1061514630
                }
            ]
        }
}
Details
{
    "promotion": 
        {
            "name": "Happy new year",
            "ends_at": "2022-03-04T16:59:59Z",
            "id": 1024173229,
            "starts_at": "2022-03-04T03:54:00Z",
            "value": 10000.0000,
            "discount_type": "fixed_amount",
            "applies_to_resource": "product_variant",
            "applies_to_quantity": 0,
            "applies_to_id": 0,
            "order_over": 1000000,
            "promotion_apply_type": 2,
            "variants": [
                {
                    "product_id": 1028183633,
                    "variant_id": 1061514629
                },
                {
                    "product_id": 1028183633,
                    "variant_id": 1061514630
                }
            ],
            "created_at": "2024-06-17T05:22:22.4108288Z",
            "updated_at": "2024-06-17T05:22:22.4108459Z",
            "first_name": "--",
            "last_name": null,
            "create_user": 200002377565,
            "applies_customer_group_id": null,
            "status": "enabled",
            "products_selection": "variant_prerequisite",
            "customers_selection": "all",
            "provinces_selection": "all",
            "channels_selection": "all",
            "locations_selection": "all",
            "entitled_collection_ids": [],
            "entitled_product_ids": [],
            "entitled_variant_ids": [
                1061514629, 1061514630
            ],
            "entitled_customer_ids": [],
            "entitled_customer_segment_ids": [],
            "entitled_province_ids": [],
            "entitled_channels": [],
            "entitled_location_ids": [],
            "rule_customs": [],
            "take_type": "fixed_amount",
            "usage_limit": null
        }
}

Update status enable a promotion​

PUT
https://apis.haravan.com/com/discounts/{promotion_id}/enable.json

Update status enable a promotion.

  • PUT https://apis.haravan.com/com/discounts/1024177200/enable.json
{}
Details
HTTP/1.1 200 OK
{
    "discount": {
        "applies_once": false,
        "applies_to_id": null,
        "code": "Happy new year",
        "ends_at": "2022-03-04T16:59:59Z",
        "id": 1024177200,
        "minimum_order_amount": 1000000.0,
        "starts_at": "2022-03-03T17:00:00Z",
        "status": "enabled",
        "usage_limit": 0,
        "value": 10000.0000,
        "discount_type": "fixed_amount",
        "times_used": 0,
        "is_promotion": false,
        "applies_to_resource": "product_variant",
        "variants": [
            {
                "product_id": 1028183633,
                "variant_id": 1061514629
            },
            {
                "product_id": 1028183633,
                "variant_id": 1061514630
            }
        ],
        "location_ids": null,
        "create_user": 200000497867,
        "first_name": null,
        "last_name": null,
        "applies_customer_group_id": null,
        "created_at": "2022-03-04T07:58:40.772Z",
        "updated_at": "2022-03-04T08:04:57.1469947Z",
        "promotion_apply_type": 2,
        "applies_to_quantity": 0,
        "order_over": 1000000,
        "is_new_coupon": true,
        "channel": null,
        "max_amount_apply": null,
        "is_advance_same_price_discount": false,
        "advance_same_prices": null,
        "once_per_customer": false,
        "products_selection": "variant_prerequisite",
        "customers_selection": "customer_prerequisite",
        "provinces_selection": "all",
        "channels_selection": "channel_prerequisite",
        "locations_selection": "location_prerequisite",
        "entitled_collection_ids": [],
        "entitled_product_ids": [],
        "entitled_variant_ids": [
            1124400234,
            1124400233
        ],
        "entitled_customer_ids": [
            1128891111
        ],
        "entitled_customer_segment_ids": [],
        "entitled_province_ids": [],
        "entitled_channels": [
            "pos",
            "web",
            "harasocial"
        ],
        "entitled_location_ids": [
            1690961
        ],
        "rule_customs": [
            {
                "name": "time_range",
                "value": "[{\"name\":\"monday\",\"value_range\":[]},{\"name\":\"tuesday\",\"value_range\":[]},{\"name\":\"wednesday\",\"value_range\":[]},{\"name\":\"thursday\",\"value_range\":[]}]"
            }
        ],
        "take_type": "fixed_amount"
    }
}

Update status disable a promotion​

PUT
https://apis.haravan.com/com/discounts/{promotion_id}/disable.json

Update status disable a promotion.

  • PUT https://apis.haravan.com/com/discounts/1017981791/disable.json
{}
Details
HTTP/1.1 200 OK
{
    "discount": {
        "applies_once": false,
        "applies_to_id": null,
        "code": "Happy new year",
        "ends_at": "2022-03-04T16:59:59Z",
        "id": 1024177200,
        "minimum_order_amount": 1000000.0,
        "starts_at": "2022-03-03T17:00:00Z",
        "status": "disabled",
        "usage_limit": 0,
        "value": 10000.0000,
        "discount_type": "fixed_amount",
        "times_used": 0,
        "is_promotion": false,
        "applies_to_resource": "product_variant",
        "variants": [
            {
                "product_id": 1028183633,
                "variant_id": 1061514629
            },
            {
                "product_id": 1028183633,
                "variant_id": 1061514630
            }
        ],
        "location_ids": null,
        "create_user": 200000497867,
        "first_name": null,
        "last_name": null,
        "applies_customer_group_id": null,
        "created_at": "2022-03-04T07:58:40.772Z",
        "updated_at": "2022-03-04T08:06:28.493101Z",
        "promotion_apply_type": 2,
        "applies_to_quantity": 0,
        "order_over": 1000000,
        "is_new_coupon": true,
        "channel": null,
        "max_amount_apply": null,
        "is_advance_same_price_discount": false,
        "advance_same_prices": null,
        "once_per_customer": false,
        "products_selection": "variant_prerequisite",
        "customers_selection": "customer_prerequisite",
        "provinces_selection": "all",
        "channels_selection": "channel_prerequisite",
        "locations_selection": "location_prerequisite",
        "entitled_collection_ids": [],
        "entitled_product_ids": [],
        "entitled_variant_ids": [
            1124400234,
            1124400233
        ],
        "entitled_customer_ids": [
            1128891111
        ],
        "entitled_customer_segment_ids": [],
        "entitled_province_ids": [],
        "entitled_channels": [
            "pos",
            "web",
            "harasocial"
        ],
        "entitled_location_ids": [
            1690961
        ],
        "rule_customs": [
            {
                "name": "time_range",
                "value": "[{\"name\":\"monday\",\"value_range\":[]},{\"name\":\"tuesday\",\"value_range\":[]},{\"name\":\"wednesday\",\"value_range\":[]},{\"name\":\"thursday\",\"value_range\":[]}]"
            }
        ],
        "take_type": "fixed_amount"
    }
}

Delete a promotion​

DELETE
https://apis.haravan.com/com/promotions/{promotion_id}.json

Delete a promotion.

  • DELETE https://apis.haravan.com/com/promotions/1024177200.json
{}
Details
HTTP/1.1 200 OK
{}