Create Coupon - Salla Merchants APIs

This endpoint allows you to create Single Coupon, and Group Coupons.

Information

Although the response payload you will be receiving of the two coupon types at once, each has its own required Body Requests.

Single Coupon

Group Coupons

When creating a Single Coupon, ensure that you are sending the following required variables:

Attribute	Type	Is Required
`code`	string	Yes
`type`	string	Yes
`amount`	number	Yes
`free_shipping`	boolean	Yes
`expiry_date`	string	Yes
`exclude_sale_products`	boolean	Yes

If marketing_active is valued as true, then when creating Marketing Coupons, ensure that you are sending the
following required variables:

Attribute	Type	Is Required
`marketing_active`	boolean	Yes
`marketing_name`	string	Yes
`marketing_type`	string	Yes
`marketing_amount`	number	Yes

Scopes

marketing.read_write- Marketing Read & Write

Request

Authorization

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Body Params application/json

code

string

optional

Coupon Code. List Coupons Code can be found here.

Example:

TestCoupon001

type

enum<string>

optional

Coupon Type.

Allowed values:

PercentagepercentageFixedfixedFfPp

Example:

percentage

amount

number

optional

Coupon Amount.

Example:

400

status

string

optional

Coupon Status.

Example:

inactive

start_date

string <date-time>

optional

Coupon Start Date. Supports two formats, either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS

Example:

2022-12-28 | 2022-12-28 10:50:01

expiry_date

string <date-time>

optional

Coupon Expiry Date. Value MUST be at least one day later than today. Supports two formats, either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS

Example:

2022-12-29 | 2022-12-29 11:55:21

applied_in

enum<string>

optional

Coupon to be applied at. Value can either all or web or app

Allowed values:

allwebapp

Example:

all

is_group

boolean

optional

Whether or not the Coupon is of type Group.

Default:

true

is_apply_with_offer

boolean | null

optional

In case the variable is set to true, the coupon will be applied with the created offer that has an apply with coupon option activated in the offers; otherwise, it will not be applied.

group_name

string

optional

Group Name. requiredif is_group value is true

Example:

Deals

group_coupons_count

integer

optional

Group Coupons Count. requiredif is_group value is true

Example:

group_suffix

string

optional

Group Name Suffix. requiredif is_group value is true. No spaces/numbers are allowed

<= 5 characters

Example:

xyz

usage_limit

number

optional

Coupon Usage Limit

Example:

usage_limit_per_user

number

optional

Coupon Usage Limit Per User

Example:

minimum_amount

number

optional

Coupon Minimum Amount

Example:

maximum_amount

number

optional

Coupon Maximum Amount. requiredif type is set to percentage

Example:

400

free_shipping

boolean

optional

Whether or not the coupon include free shipping

Default:

true

exclude_sale_products

boolean

optional

Whether or not the coupon exclude on-sale products

Default:

true

show_maximum_amount

boolean

optional

Whether or not to show the maximum amount of the coupon

Default:

true

marketing_show_maximum_amount

boolean

optional

Whether or not to show the marketing maximum amount of the coupon to the marketer

Default:

true

marketing_active

boolean

optional

Whether or not the coupon include a marketer

Default:

true

marketing_name

string

optional

Marketer Name.

Example:

User Test Marketing

marketing_type

enum<string>

optional

Marketer Type.

Allowed values:

PercentagepercentageFixedfixedFfPp

Example:

Percentage

marketing_amount

number

optional

Marketing Amount.

Example:

marketing_hide_total_sales

boolean

optional

Whether or not hide total sales.

Default:

true

marketing_maximum_amount

number

optional

Marketing Maximum Amount Value

Example:

marketing_info

string

optional

Marketing Additional Info

Example:

Additional Info

beneficiary_domain

string

optional

Beneficiary Email Domain

Example:

test.test

products_include

array[string]

optional

List of Included Products in the Coupon. List of products can be found here.

list_include_categories

array[string]

optional

List of Included Categories in the Coupon. List of categories can be found here.

products_exclude

array[string]

optional

List of Excluded Products in the Coupon. List of products can be found here.

list_exclude_categories

array[string]

optional

List of Excluded Categories. List of categories can be found here.

list_exclude_brands

array[string]

optional

List of Excluded Brands. List of brands can be found here.

list_include_groups

array[string]

optional

List of Included Customer Groups. List of customers can be found here.

list_exclude_groups

array[string]

optional

List of Excluded Customer Groups. List of customers can be found here.

list_exclude_shipping

array[string]

optional

List of Excluded Shipping Companies. List of shipping companies can be found here

payment_methods

array[string]

optional

List of Included Payment Methods. List of available payment methods can be found here.

Allowed values:

allapple_paybankcodcredit_cardknetmadapaypalspotii_paystc_paytabby_installmenttamara_installment

Example

{
  "code": "discount10",
  "type": "percentage",
  "amount": 10,
  "maximum_amount": 50,
  "free_shipping": true,
  "start_date": "2022-08-02",
  "expiry_date": "2022-12-12",
  "exclude_sale_products": false,
  "is_apply_with_offer": true
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

status

number

optional

Response status code, a numeric or alphanumeric identifier used to convey the outcome or status of a request, operation, or transaction in various systems and applications, typically indicating whether the action was successful, encountered an error, or resulted in a specific condition.

success

boolean

optional

Response flag, boolean indicator used to signal a particular condition or state in the response of a system or application, often representing the presence or absence of certain conditions or outcomes.

data

object (Coupon)

optional

number

required

Coupon unique identifier. List of Coupon ID can be found here.

Example:

815296212

code

string

required

Coupon code.

Example:

AAVVC

type

enum<string>

required

Coupon type.

Allowed values:

percentagePercentagefixedFixedfp

Example:

percentage

status

enum<string>

required

Coupon status.

Allowed values:

activeinactivedeleted

Example:

active

is_apply_with_offer

boolean | null

optional

In case the variable is set to true, the coupon will be applied with the created offer that has an apply with coupon option activated in the offers; otherwise, it will not be applied.

amount

object

required

Coupon amount.

minimum_amount

object

required

The minimum coupon amount.

maximum_amount

object

required

The maximum coupon amount.

show_maximum_amount

boolean

required

Whether or not to show the coupon's maximum amount

Default:

false

expiry_date

string

required

Coupon expiry date. Value MUST be at least one day later than today. Supports two formats, either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS

Example:

2022-12-31 12:59:59

start_date

string

required

Coupon start date. Supports two formats, either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS

Example:

2022-12-28 12:59:59

free_shipping

boolean

required

Whether or not to the coupon includes free shipping

Default:

true

usage_limit

number

required

Coupon's usage limit

Example:

usage_limit_per_user

number

required

Coupon's usage limit per user

Example:

include_product_ids

array[string]

required

List of included products IDs. List of products ca be found [here]https://docs.salla.dev/api-5394168).

exclude_product_ids

array[string]

required

List of excluded product IDs. List of products ca be found [here]https://docs.salla.dev/api-5394168).

is_sale_products_exclude

boolean

required

Whether or not to exclude On-Sale Products

Default:

true

include_category_ids

array[string]

required

List of included product Category IDs. List of categories can be found [here] (https://docs.salla.dev/api-5394207)

exclude_category_ids

array[string]

required

List of included Category IDs. List of categories can be found [here] (https://docs.salla.dev/api-5394207)

include_customer_group_ids

array[string]

required

List of included Customer Group IDs. List of customer groups can be found [here] (https://docs.salla.dev/api-5394129)

exclude_customer_group_ids

array[string]

required

List of excluded Customer Group IDs. List of customer groups can be found [here] (https://docs.salla.dev/api-5394129)

exclude_brands_ids

array[string]

required

List of excluded Brand IDs. List of brands can be found [here] (https://docs.salla.dev/api-5394213)

exclude_shipping_ids

array[string]

required

List of excluded Shipment Company IDs. Shipping companies list can be found here

include_customer_ids

array[string]

required

List of excluded Customer IDs. List of customers can be found [here] (https://docs.salla.dev/api-5394121)

include_payment_methods

array[string]

required

List of included Payment Methods. List of Available Payment Methods can be found here.

Allowed values:

allapple_paybankcodcredit_cardknetmadapaypalspotii_paystc_paytabby_installmenttamara_installment

applied_in

enum<string>

required

Coupon to be applied at. Value can either all or web or app

Allowed values:

allwebapp

Example:

all

is_group

boolean

required

Whether or not the Coupon is part of a group of Coupons

Default:

true

group_name

string | null

required

Coupon Group Name. requiredif is_group = true; otherwise returns null value

Example:

Grouping1

group_coupons_count

number | null

required

Coupon Group Count.requiredif is_group = true; otherwise returns null value

Example:

group_coupon_suffix

string | null

required

Coupon Group Suffix. requiredif is_group = true; otherwise returns null value

Example:

xyz

group_coupons

array [object {1}]

required

Group Coupons. requiredif is_group = true; otherwise returns null value

beneficiary_domain

string | null

required

Beneficiary’s email domain name

Example:

domain.test

statistics

object

required

Coupon statistics.

Example:

domain.test

created_at

object

required

Date and time of creating the coupon.

updated_at

object

required

Date and time of updating the coupon.

marketing_active

boolean

required

Whether or not the Marketing is active for a certain Coupon

Default:

true

marketing_name

string | null

required

Marketer name assoicated to the Coupon. requiredif marketing_active = true; otherwise returns null value

Example:

User Name

marketing_email

string | null

required

Marketer email assoicated to the Coupon. Value may appear if marketing_acive: true; otherwise returns null value.

Example:

[email protected]

marketing_type

enum<string>

required

Coupon type.

Allowed values:

percentagePercentagefixedFixedfp

Example:

percentage

marketing_amount

object | null

required

The amount due to the marketer. requiredif marketing_active = true; otherwise returns null value

marketing_hide_total_sales

boolean | null

required

Whether or not to hide the total sales from the marketer's stastics page. Value may appear if marketing_acive: true; otherwise returns null value.

Default:

false

marketing_show_maximum_amount

boolean | null

required

Whether or not to show the maximum amount of marketing amount to the marketers. Value may appear if marketing_acive: true; otherwise returns null value.

Default:

true

marketing_maximum_amount

number | null

required

Marketing maximum amount. Value may appear if marketing_acive: true; otherwise returns null value.

Default:

Example:

4000

marketing_info

string | null

required

Additional notes to the Marketer. Value may appear if marketing_acive: true; otherwise returns null value.

Example:

Additional Notes

marketing_visits_count

number | null

required

Marketing visit counts. Value may appear if marketing_acive: true; otherwise returns null value.

Example:

marketing_url

string | null

required

Marketing URL. Value may appear if marketing_acive: true; otherwise returns null value.

Example:

https://salla.sa/teststore?utm_source=ref&utm_campaign=QAZCVS

marketing_statistics_url

string | null

required

Marketing statistics URL. value may appear if marketing_acive: true; otherwise returns null value.

Example:

https://mtjr.coupons/VvVMP

Examples

Example | Single Coupon ResponseExample | Group Coupon Response

{
  "status": 200,
  "success": true,
  "data": {
    "id": 1622617640,
    "code": "QAZCVS",
    "type": "fixed",
    "status": "active",
    "is_apply_with_offer": true,
    "amount": {
      "amount": 30,
      "currency": "SAR"
    },
    "minimum_amount": null,
    "maximum_amount": {
      "amount": 0,
      "currency": "SAR"
    },
    "show_maximum_amount": false,
    "expiry_date": "2023-03-17 00:00:00",
    "start_date": null,
    "free_shipping": true,
    "usage_limit": null,
    "usage_limit_per_user": null,
    "include_product_ids": [
      "1626467363"
    ],
    "exclude_product_ids": [
      "213592621"
    ],
    "is_sale_products_exclude": true,
    "include_category_ids": [
      "676928739"
    ],
    "exclude_category_ids": [
      "1585249762"
    ],
    "include_customer_group_ids": [
      "322729604"
    ],
    "exclude_customer_group_ids": [
      "1830458757"
    ],
    "exclude_brands_ids": [
      "1939592358"
    ],
    "exclude_shipping_ids": [
      "1345871747"
    ],
    "include_customer_ids": [],
    "include_payment_methods": [
      "bank",
      "cod",
      "credit_card",
      "knet",
      "mada",
      "paypal",
      "spotii_pay",
      "stc_pay",
      "tabby_installment",
      "tamara_installment"
    ],
    "applied_in": "all",
    "is_group": false,
    "group_name": null,
    "group_coupons_count": null,
    "group_coupon_suffix": null,
    "group_coupons": null,
    "beneficiary_domain": null,
    "statistics": {
      "num_of_usage": 0,
      "num_of_customers": 0,
      "coupon_sales": {
        "amount": 0,
        "currency": "SAR"
      }
    },
    "created_at": {
      "date": "2022-04-06 12:45:13.000000",
      "timezone_type": 3,
      "timezone": "Asia/Riyadh"
    },
    "updated_at": {
      "date": "2022-04-06 12:45:13.000000",
      "timezone_type": 3,
      "timezone": "Asia/Riyadh"
    },
    "marketing_active": true,
    "marketing_name": "Nabil",
    "marketing_type": "percentage",
    "marketing_amount": {
      "amount": 10,
      "currency": "SAR"
    },
    "marketing_hide_total_sales": false,
    "marketing_show_maximum_amount": false,
    "marketing_maximum_amount": 4000,
    "marketing_info": "",
    "marketing_visits_count": 0,
    "marketing_url": "https://salla.sa/dev-wofftr4xsra5xtlv?utm_source=ref&utm_campaign=QAZCVS",
    "marketing_statistics_url": "https://mtjr.coupons/w172T"
  }
}

🟠422Error Validation

🟠401Unauthorized