Salla Docs
Merchant API
Partner APIs
Storefront
Salla CLI
Salla Docs

    [lightMode]

    List Coupons

    GET/coupons
    [updatedIn] 2 months ago

    This endpoint allows you to return a list of coupons.

    `marketing.read`- Marketing Read Only

    Request

    Authorization: OAuth 2.0
    Add the parameter
    Authorization
    to [header]    ，whose value is to concatenate the Token after the Bearer.
    [api.label.example]
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    [message.queryParameter]
    keyword
    string 
    optional

    Listing the coupons by keywords.

    Request samples

    [api.label.responses]

    Success(200)
    HTTP Code: 200
    Content Type : JSONapplication/json
    [response.label.jsonSchema]
    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
    array[object (Coupon) {46}] 
    optional
    id
    number 
    required

    Coupon ID. List Coupon ID can be found here.

    Example:
    815296212
    code
    string 
    required

    Coupon Code

    Example:
    AAVVC
    type
    enum<string> 
    required

    Coupon Type.

    Allowed values:
    PercentagepercentageFixedfixedFfPp
    Example:
    percentage
    status
    enum<string> 
    required

    Coupon Status.

    Allowed values:
    activeinactivedeleted
    Example:
    active
    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:
    89
    usage_limit_per_user
    number 
    required

    Coupon's Usage Limit Per User

    Example:
    88
    include_product_ids
    array[string]
    required

    List of included Product 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:
    90
    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>  | enum<null> 
    required

    Marketing Type. requiredif marketing_active = true; otherwise returns null value

    Allowed values:
    PercentagepercentageFixedfixedFfPp
    Example:
    fixed
    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:
    0
    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:
    33
    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
    pagination
    object (Pagination) 
    optional

    For a better response behavior as well as maintain the best security level, All retrieving API endpoints use a mechanism to retrieve data in chunks called pagination. Pagination working by return only a specific number of records in each response, and through passing the page number you can navigate the different pages.

    count
    number 
    required

    Number of returned results.

    total
    number 
    required

    Number of all results.

    perPage
    number 
    required

    Number of results per page.

    <= 65
    currentPage
    number 
    required

    Number of current page.

    totalPages
    number 
    required

    Number of total pages.

    links
    object 
    required

    Array of linkes to next and previous pages.

    [api.label.example]
    {
  "status": 200,
  "success": true,
  "data": [
    {
      "id": 6930446,
      "code": "DEAL",
      "type": "fixed",
      "status": "active",
      "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": [],
      "exclude_product_ids": [],
      "is_sale_products_exclude": true,
      "include_category_ids": [],
      "exclude_category_ids": [],
      "include_customer_group_ids": [],
      "exclude_customer_group_ids": [],
      "exclude_brands_ids": [],
      "exclude_shipping_ids": [],
      "include_payment_methods": [],
      "applied_in": "all",
      "is_group": true,
      "group_name": "Deals",
      "group_coupons_count": 3,
      "group_coupon_suffix": "DEAL",
      "group_coupons": [
        {
          "code": "DEAL5Wsl"
        },
        {
          "code": "DEALgaNN"
        },
        {
          "code": "DEALFRa7"
        }
      ],
      "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:55:06.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "updated_at": {
        "date": "2022-04-06 12:55:06.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "marketing_active": false,
      "marketing_name": null,
      "marketing_type": null,
      "marketing_amount": null,
      "marketing_hide_total_sales": false,
      "marketing_show_maximum_amount": false,
      "marketing_maximum_amount": null,
      "marketing_info": null,
      "marketing_visits_count": null,
      "marketing_url": null,
      "marketing_statistics_url": null
    },
    {
      "id": 1622617640,
      "code": "QAZCVS",
      "type": "fixed",
      "status": "active",
      "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": [],
      "exclude_product_ids": [],
      "is_sale_products_exclude": true,
      "include_category_ids": [],
      "exclude_category_ids": [],
      "include_customer_group_ids": [],
      "exclude_customer_group_ids": [],
      "exclude_brands_ids": [],
      "exclude_shipping_ids": [],
      "include_payment_methods": [],
      "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_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"
    },
    {
      "id": 242399780,
      "code": "azvfpsv",
      "type": "fixed",
      "status": "active",
      "amount": {
        "amount": 30,
        "currency": "SAR"
      },
      "minimum_amount": {
        "amount": 100,
        "currency": "SAR"
      },
      "maximum_amount": {
        "amount": 50,
        "currency": "SAR"
      },
      "show_maximum_amount": false,
      "expiry_date": "2023-03-17 00:00:00",
      "start_date": "2022-04-24 06:00:00",
      "free_shipping": true,
      "usage_limit": 10,
      "usage_limit_per_user": 1,
      "include_product_ids": [
        1261174103
      ],
      "exclude_product_ids": [
        277818017
      ],
      "is_sale_products_exclude": true,
      "include_category_ids": [
        256950451,
        2064430530
      ],
      "exclude_category_ids": [
        307036893
      ],
      "include_customer_group_ids": [
        667738032
      ],
      "exclude_customer_group_ids": [],
      "exclude_brands_ids": [
        1097509908
      ],
      "exclude_shipping_ids": [
        1935030040
      ],
      "include_payment_methods": [
        "all"
      ],
      "applied_in": "all",
      "is_group": false,
      "group_name": null,
      "group_coupons_count": null,
      "group_coupon_suffix": null,
      "group_coupons": null,
      "beneficiary_domain": "salla.sa",
      "statistics": {
        "num_of_usage": 0,
        "num_of_customers": 0,
        "coupon_sales": {
          "amount": 0,
          "currency": "SAR"
        }
      },
      "created_at": {
        "date": "2022-04-06 12:38:06.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "updated_at": {
        "date": "2022-04-06 12:59:14.000000",
        "timezone_type": 3,
        "timezone": "Asia/Riyadh"
      },
      "marketing_active": true,
      "marketing_name": "User Name",
      "marketing_type": "percentage",
      "marketing_amount": {
        "amount": 5,
        "currency": "SAR"
      },
      "marketing_hide_total_sales": false,
      "marketing_show_maximum_amount": true,
      "marketing_maximum_amount": 4000,
      "marketing_info": "Marketing coupon for User Name",
      "marketing_visits_count": 0,
      "marketing_url": "https://salla.sa/dev-wofftr4xsra5xtlv?utm_source=ref&utm_campaign=azvfpsv",
      "marketing_statistics_url": "https://mtjr.coupons/eqOuz"
    }
  ],
  "pagination": {
    "count": 3,
    "total": 3,
    "perPage": 15,
    "currentPage": 1,
    "totalPages": 1,
    "links": []
  }
}
    [updatedIn] 2 months ago