List Coupons - Zid Docs

Retrieves a list of all available coupons from the system. The response includes active, inactive, and expired coupons along with relevant metadata such as store details, discount type, and validity period.

🔑Scopes

coupons.read - Coupons Read

Request

Query Params

page

integer

required

The page number of results for pagination.

Example:

per_page

integer

required

The number of results per page.

Example:

search_term

string

optional

The term used to search for specific coupons.

total_usage_value

integer

optional

The total number of times a coupon has been used.

Example:

total_usage_compare

string

optional

Comparison operator for filtering by total usage.

Example:

discount_status

string

optional

The status of the discount.

Example:

coupon_inactive

date_from

string

optional

The start date for filtering results based on date range.

Example:

2019-09-19

date_to

string

optional

The end date for filtering results based on date range.

Example:

2019-09-29

date_attribute

string

optional

The attribute used for filtering by date.

Example:

date_start

order_by

string

optional

The field by which results should be ordered.

Example:

status_code

sort_type

string

optional

The sorting order.

Example:

desc

discount_type

string

optional

The type of discount applied (p for percentage).

Example:

Header Params

string

required

Specifies the Media Types acceptable for the client. In this case, it signals that the client expects a response in the JSON format.

Example:

application/json

Authorization

string

required

The Authorization token is a unique key given to the third-party application (Partner) by Zid. It is used to authenticate the API requests made by the Partner application. The token verifies the partner's identity and ensures they have permission to access Zid's API but does not provide any specific user or store information. It should be included in the header of API requests when the partner application needs to access Zid's API.

Example:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y

X-Manager-Token

string

required

This token is used to authenticate and access information related to the store. It is obtained through an OAuth mechanism and is required to perform operations on the store's data. The X-Manager-Token should be included in the header of API requests that require store-related information.

Example:

eyJpdiI6IlA3WTFZbWk1YVBTQnNrYkRtOFBGZGc9PSIsInZhbHVlIjoiL3QvVmtuMHFQdGNMdkNwZ0FCZkh3Y1l4aEs5NDhGVnFXbWVZYlFJb2kucdcNrekppN09CVTlnYlducjRLbjhXNzhFTFhhZDZTSXdRbUphSEYyUkZJWTJFZ0h3Ymlzb1RVNmxlaEkjgftrmpIZ1RmZXVFYUszZG5DZDZjbTRqNzByNVBMTktzYkQ3WGQ5MDhqbWo2NWFkT3MvRExmYVY4YXBCakkwSjR1L2pTbUR4dWZvd2h5K2tTQlAvRlN2TnZuOVFROW42WTRqZmtkWUZWem4rRXFLVU00aGJtQT0iLCJtYWMiOiJjM2U2ZGRmMjY1ZjFmMmI5YjZlMzFkMGFhNmMzYjM5ZjhiOWE0YjVhMzU2ZTRhYTkxOTVlYmFiMTVkY2I1NWQ2IiwidGFnIjoiIn0=

Accept-Language

string

required

Preferred language for the response. Defaults to en if not specified.

Example:

User-Agent

string

required

The User-Agent header contains information about the user agent (browser or app) making the request. It allows the server to provide a tailored response depending on the user agent's capabilities and preferences.

Example:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request GET 'https://api.zid.sa/v1/managers/store/coupons?page=1&per_page=15&search_term=&total_usage_value=1&total_usage_compare=>&discount_status=coupon_inactive&date_from=2019-09-19&date_to=2019-09-29&date_attribute=date_start&order_by=status_code&sort_type=desc&discount_type=p' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y' \
--header 'X-Manager-Token: eyJpdiI6IlA3WTFZbWk1YVBTQnNrYkRtOFBGZGc9PSIsInZhbHVlIjoiL3QvVmtuMHFQdGNMdkNwZ0FCZkh3Y1l4aEs5NDhGVnFXbWVZYlFJb2kucdcNrekppN09CVTlnYlducjRLbjhXNzhFTFhhZDZTSXdRbUphSEYyUkZJWTJFZ0h3Ymlzb1RVNmxlaEkjgftrmpIZ1RmZXVFYUszZG5DZDZjbTRqNzByNVBMTktzYkQ3WGQ5MDhqbWo2NWFkT3MvRExmYVY4YXBCakkwSjR1L2pTbUR4dWZvd2h5K2tTQlAvRlN2TnZuOVFROW42WTRqZmtkWUZWem4rRXFLVU00aGJtQT0iLCJtYWMiOiJjM2U2ZGRmMjY1ZjFmMmI5YjZlMzFkMGFhNmMzYjM5ZjhiOWE0YjVhMzU2ZTRhYTkxOTVlYmFiMTVkY2I1NWQ2IiwidGFnIjoiIn0=' \
--header 'Accept-Language: en' \
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36'

Responses

🟢200Success

application/json

Body

status

string

optional

Status of the API response.

Example:

success

coupons

array [object {19}]

optional

List of available coupons.

coupon_id

integer

optional

Unique coupon identifier.

Example:

3250

integer

optional

Coupon ID.

Example:

3250

store_id

integer

optional

ID of the store offering the coupon.

Example:

550

store_name

string

optional

Name of the store.

Example:

MBasideq Store

store_logo

string <uri>

optional

URL of the store logo.

Example:

https://example.com/logo.png

code

string

optional

Coupon code.

Example:

1234

uses_total

integer

optional

Total times the coupon has been used.

Example:

created_at

string <date-time>

optional

Timestamp when the coupon was created.

Example:

2025-01-19T09:11:59.000000Z

name

string

optional

Coupon name.

Example:

خصم اختباري

discount_type

string

optional

Type of discount (p = percentage, f = fixed amount).

Example:

applying_method

string

optional

Method of coupon application.

Example:

CODE

conditions

array[string] | null

optional

Conditions for coupon application.

Example:

null

discount

number

optional

Discount value.

Example:

free_shipping

boolean

optional

Whether the coupon offers free shipping.

Example:

true

free_cod

boolean

optional

Whether the coupon offers free cash-on-delivery.

Example:

false

apply_to

string

optional

Applicable scope of the coupon.

Example:

all

date_start

string <date>

optional

Coupon start date.

Example:

2025-01-19

date_end

string <date>

optional

Coupon end date.

Example:

2025-02-19

coupon_status

boolean

optional

Indicates if the coupon is currently active.

Example:

true

count

integer

optional

Total number of coupons.

Example:

111

active_coupons_count

integer

optional

Number of active coupons.

Example:

inactive_coupons_count

integer

optional

Number of inactive coupons.

Example:

expired_coupons_count

integer

optional

Number of expired coupons.

Example:

110

pagination

object

optional

Pagination details.

page

integer

optional

Current page number.

Example:

page_size

integer

optional

Number of items per page.

Example:

next_page

integer

optional

Next page number.

Example:

last_page

integer

optional

Last available page.

Example:

result_count

integer

optional

Total results count.

Example:

111

message

object

optional

Message details.

code

string | null

optional

Message code.

Example:

null

name

string | null

optional

Message name.

Example:

null

description

string | null

optional

Message description.

Example:

null

Example

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Status of the API response",
      "example": "success"
    },
    "coupons": {
      "type": "array",
      "description": "List of available coupons",
      "items": {
        "type": "object",
        "properties": {
          "coupon_id": {
            "type": "integer",
            "description": "Unique coupon identifier",
            "example": 3250
          },
          "id": {
            "type": "integer",
            "description": "Coupon ID (same as coupon_id)",
            "example": 3250
          },
          "store_id": {
            "type": "integer",
            "description": "ID of the store offering the coupon",
            "example": 550
          },
          "store_name": {
            "type": "string",
            "description": "Name of the store",
            "example": "MBasideq Store"
          },
          "store_logo": {
            "type": "string",
            "format": "uri",
            "description": "URL of the store logo",
            "example": "https://example.com/logo.png"
          },
          "code": {
            "type": "string",
            "description": "Coupon code",
            "example": "1234"
          },
          "uses_total": {
            "type": "integer",
            "description": "Total times the coupon has been used",
            "example": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the coupon was created",
            "example": "2025-01-19T09:11:59.000000Z"
          },
          "name": {
            "type": "string",
            "description": "Coupon name",
            "example": "خصم اختباري"
          },
          "discount_type": {
            "type": "string",
            "description": "Type of discount (p = percentage, f = fixed amount)",
            "example": "p"
          },
          "applying_method": {
            "type": "string",
            "description": "Method of coupon application",
            "example": "CODE"
          },
          "conditions": {
            "type": [
              "array",
              "null"
            ],
            "description": "Conditions for coupon application",
            "example": null
          },
          "discount": {
            "type": "number",
            "description": "Discount value",
            "example": 10
          },
          "free_shipping": {
            "type": "boolean",
            "description": "Whether the coupon offers free shipping",
            "example": true
          },
          "free_cod": {
            "type": "boolean",
            "description": "Whether the coupon offers free cash-on-delivery",
            "example": false
          },
          "apply_to": {
            "type": "string",
            "description": "Applicable scope of the coupon",
            "example": "all"
          },
          "date_start": {
            "type": "string",
            "format": "date",
            "description": "Coupon start date",
            "example": "2025-01-19"
          },
          "date_end": {
            "type": "string",
            "format": "date",
            "description": "Coupon end date",
            "example": "2025-02-19"
          },
          "coupon_status": {
            "type": "boolean",
            "description": "Indicates if the coupon is currently active",
            "example": true
          }
        }
      }
    },
    "count": {
      "type": "integer",
      "description": "Total number of coupons",
      "example": 111
    },
    "active_coupons_count": {
      "type": "integer",
      "description": "Number of active coupons",
      "example": 1
    },
    "inactive_coupons_count": {
      "type": "integer",
      "description": "Number of inactive coupons",
      "example": 0
    },
    "expired_coupons_count": {
      "type": "integer",
      "description": "Number of expired coupons",
      "example": 110
    },
    "pagination": {
      "type": "object",
      "description": "Pagination details",
      "properties": {
        "page": {
          "type": "integer",
          "description": "Current page number",
          "example": 1
        },
        "page_size": {
          "type": "integer",
          "description": "Number of items per page",
          "example": 15
        },
        "next_page": {
          "type": "integer",
          "description": "Next page number",
          "example": 2
        },
        "last_page": {
          "type": "integer",
          "description": "Last available page",
          "example": 8
        },
        "result_count": {
          "type": "integer",
          "description": "Total results count",
          "example": 111
        }
      }
    },
    "message": {
      "type": "object",
      "description": "Message details",
      "properties": {
        "code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Message code",
          "example": null
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Message name",
          "example": null
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Message description",
          "example": null
        }
      }
    }
  }
}