Coupons API

Create and manage discount coupons for your store.

List Coupons

http

GET /api/external/v1/coupons

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)
`status`	string	Filter: `active`, `inactive`, `expired`, `scheduled`
`type`	string	Filter: `percentage`, `fixed_amount`, `free_shipping`
`search`	string	Search in code and name

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/coupons?status=active&type=percentage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "SUMMER25",
      "name": "Summer Sale 25% Off",
      "description": "25% off all products during summer sale",
      "type": "percentage",
      "value": "25.00",
      "minimum_order_amount": "10.00",
      "maximum_discount": "50.00",
      "usage_limit": 100,
      "usage_limit_per_customer": 1,
      "times_used": 42,
      "is_active": true,
      "first_order_only": false,
      "starts_at": "2025-06-01T00:00:00Z",
      "expires_at": "2025-08-31T23:59:59Z",
      "created_at": "2025-05-15T10:30:00Z",
      "updated_at": "2025-05-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 15,
    "total": 18
  }
}

Get Single Coupon

http

GET /api/external/v1/coupons/{id}

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/coupons/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "code": "SUMMER25",
    "name": "Summer Sale 25% Off",
    "description": "25% off all products during summer sale",
    "type": "percentage",
    "value": "25.00",
    "minimum_order_amount": "10.00",
    "maximum_discount": "50.00",
    "usage_limit": 100,
    "usage_limit_per_customer": 1,
    "times_used": 42,
    "applicable_products": null,
    "applicable_categories": null,
    "excluded_products": null,
    "is_active": true,
    "first_order_only": false,
    "starts_at": "2025-06-01T00:00:00Z",
    "expires_at": "2025-08-31T23:59:59Z",
    "created_at": "2025-05-15T10:30:00Z",
    "updated_at": "2025-05-15T10:30:00Z"
  }
}

Create Coupon

http

POST /api/external/v1/coupons

Request Body

Parameter	Type	Required	Description
`code`	string	No	Unique coupon code (auto-generated if not provided)
`name`	string	Yes	Display name for the coupon
`description`	string	No	Description of the coupon
`type`	string	Yes	Discount type: `percentage`, `fixed_amount`, `free_shipping`
`value`	number	Yes	Discount value (percentage or fixed amount)
`minimum_order_amount`	number	No	Minimum order amount required
`maximum_discount`	number	No	Maximum discount cap (for percentage discounts)
`usage_limit`	integer	No	Total usage limit across all customers
`usage_limit_per_customer`	integer	No	Usage limit per individual customer
`applicable_products`	array	No	Array of product IDs coupon applies to
`applicable_categories`	array	No	Array of category IDs coupon applies to
`excluded_products`	array	No	Array of product IDs to exclude
`is_active`	boolean	No	Whether coupon is active (default: true)
`first_order_only`	boolean	No	Only valid for first-time customers
`starts_at`	string	No	Start date (ISO 8601)
`expires_at`	string	No	Expiration date (ISO 8601)

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/coupons" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "name": "Welcome Discount",
    "description": "10% off for new customers",
    "type": "percentage",
    "value": 10,
    "minimum_order_amount": 5.00,
    "maximum_discount": 25.00,
    "usage_limit_per_customer": 1,
    "first_order_only": true,
    "is_active": true
  }'

Response

json

{
  "success": true,
  "data": {
    "id": 2,
    "code": "WELCOME10",
    "name": "Welcome Discount",
    "description": "10% off for new customers",
    "type": "percentage",
    "value": "10.00",
    "minimum_order_amount": "5.00",
    "maximum_discount": "25.00",
    "usage_limit": null,
    "usage_limit_per_customer": 1,
    "times_used": 0,
    "applicable_products": null,
    "applicable_categories": null,
    "excluded_products": null,
    "is_active": true,
    "first_order_only": true,
    "starts_at": null,
    "expires_at": null,
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-20T14:30:00Z"
  },
  "message": "Coupon created successfully"
}

Update Coupon

http

PUT /api/external/v1/coupons/{id}

Request Body

All fields from the create endpoint are accepted. Only include fields you want to update.

Example Request

bash

curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/coupons/2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 15,
    "maximum_discount": 30.00,
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": 2,
    "code": "WELCOME10",
    "name": "Welcome Discount",
    "description": "10% off for new customers",
    "type": "percentage",
    "value": "15.00",
    "minimum_order_amount": "5.00",
    "maximum_discount": "30.00",
    "usage_limit": null,
    "usage_limit_per_customer": 1,
    "times_used": 0,
    "is_active": true,
    "first_order_only": true,
    "starts_at": null,
    "expires_at": "2025-12-31T23:59:59Z",
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-20T15:00:00Z"
  },
  "message": "Coupon updated successfully"
}

Delete Coupon

http

DELETE /api/external/v1/coupons/{id}

Coupons with usage history are soft-deleted (archived). Coupons that have never been used are permanently deleted.

Example Request

bash

curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/coupons/2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "message": "Coupon deleted successfully"
}

Validate Coupon Code

Validate a coupon code for checkout. This endpoint checks if the coupon is valid, applicable to the customer, and calculates the discount amount.

http

POST /api/external/v1/coupons/validate

Request Body

Parameter	Type	Required	Description
`code`	string	Yes	Coupon code to validate
`subtotal`	number	Yes	Order subtotal amount
`customer_email`	string	Yes	Customer's email address
`cart_items`	array	No	Cart items for product-specific validation

Cart Item Object

Field	Type	Description
`product_id`	integer	Product ID
`category_id`	integer	Category ID
`price`	number	Item price
`quantity`	integer	Item quantity
`total`	number	Item total (price * quantity)

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/coupons/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER25",
    "subtotal": 49.99,
    "customer_email": "player@example.com",
    "cart_items": [
      {
        "product_id": 1,
        "category_id": 2,
        "price": 24.99,
        "quantity": 2,
        "total": 49.98
      }
    ]
  }'

Response (Valid Coupon)

json

{
  "success": true,
  "data": {
    "valid": true,
    "coupon": {
      "id": 1,
      "code": "SUMMER25",
      "name": "Summer Sale 25% Off",
      "type": "percentage",
      "type_label": "Percentage Off",
      "value": "25.00",
      "formatted_value": "25%",
      "discount_amount": 12.50,
      "minimum_order_amount": "10.00",
      "maximum_discount": "50.00"
    }
  }
}

Response (Invalid Coupon)

json

{
  "success": false,
  "data": {
    "valid": false,
    "message": "This coupon has expired"
  }
}

Toggle Coupon Status

Enable or disable a coupon.

http

POST /api/external/v1/coupons/{id}/toggle

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/coupons/1/toggle" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "code": "SUMMER25",
    "is_active": false
  },
  "message": "Coupon deactivated"
}

Get Coupon Statistics

Retrieve overall coupon statistics for your store.

http

GET /api/external/v1/coupons/statistics

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/coupons/statistics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "statistics": {
      "total_coupons": 18,
      "active_coupons": 12,
      "expired_coupons": 4,
      "total_usages": 342,
      "total_discount_given": "4,523.50",
      "top_coupons": [
        {
          "id": 1,
          "code": "SUMMER25",
          "name": "Summer Sale 25% Off",
          "type": "percentage",
          "value": "25.00",
          "times_used": 89
        },
        {
          "id": 3,
          "code": "FLAT10",
          "name": "$10 Off",
          "type": "fixed_amount",
          "value": "10.00",
          "times_used": 67
        }
      ]
    }
  }
}

Get Coupon Usage History

Retrieve usage history for a specific coupon.

http

GET /api/external/v1/coupons/{id}/usages

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)

Example Request

bash

curl -X GET "https://yourstore.pixlpay.net/api/external/v1/coupons/1/usages?per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "coupon": {
      "id": 1,
      "code": "SUMMER25",
      "name": "Summer Sale 25% Off",
      "times_used": 89
    },
    "usages": [
      {
        "id": 1,
        "discount_amount": "12.50",
        "created_at": "2025-07-15T14:30:00Z",
        "order": {
          "id": 156,
          "order_number": "ORD-2025-156",
          "total": "37.49",
          "payment_status": "paid",
          "customer_email": "player@example.com",
          "created_at": "2025-07-15T14:30:00Z"
        }
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "last_page": 9,
    "per_page": 10,
    "total": 89
  }
}

Duplicate Coupon

Create a copy of an existing coupon with a new unique code.

http

POST /api/external/v1/coupons/{id}/duplicate

Example Request

bash

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/coupons/1/duplicate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

json

{
  "success": true,
  "data": {
    "id": 19,
    "code": "A8K2M9PX",
    "name": "Summer Sale 25% Off (Copy)",
    "description": "25% off all products during summer sale",
    "type": "percentage",
    "value": "25.00",
    "times_used": 0,
    "is_active": true,
    "created_at": "2025-01-20T16:00:00Z",
    "updated_at": "2025-01-20T16:00:00Z"
  },
  "message": "Coupon duplicated successfully"
}

Coupon Object

Field	Type	Description
`id`	integer	Unique identifier
`code`	string	Coupon code (uppercase)
`name`	string	Display name
`description`	string	Description
`type`	string	`percentage`, `fixed_amount`, `free_shipping`
`value`	string	Discount value
`minimum_order_amount`	string	Minimum order amount required
`maximum_discount`	string	Maximum discount cap
`currency`	string	Currency code
`usage_limit`	integer	Total usage limit (null = unlimited)
`usage_limit_per_customer`	integer	Per-customer limit (null = unlimited)
`times_used`	integer	Number of times used
`applicable_products`	array	Product IDs coupon applies to
`applicable_categories`	array	Category IDs coupon applies to
`excluded_products`	array	Product IDs excluded from coupon
`is_active`	boolean	Whether coupon is active
`first_order_only`	boolean	Only for first-time customers
`starts_at`	string	Start date (ISO 8601)
`expires_at`	string	Expiration date (ISO 8601)
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Coupon Types

Type	Description
`percentage`	Percentage discount off order subtotal
`fixed_amount`	Fixed monetary discount
`free_shipping`	Free shipping on the order

Validation Errors

When validating a coupon, these are possible error messages:

Error Message	Description
`Coupon not found`	The code doesn't exist
`This coupon is no longer active`	Coupon is disabled
`This coupon has expired`	Past expiration date
`This coupon is not yet active`	Before start date
`This coupon has reached its usage limit`	Global limit reached
`This coupon is only valid for first-time customers`	Not a first order
`You have already used this coupon the maximum number of times`	Per-customer limit reached
`Minimum order amount of $X.XX required`	Subtotal too low
`No applicable products in cart for this coupon`	Product restrictions not met

API Errors

Status	Error	Description
400	Bad Request	Invalid coupon or validation failed
401	Unauthorized	Invalid or missing token
403	Forbidden	Token lacks `coupons:read` or `coupons:write` scope
404	Not Found	Coupon doesn't exist
422	Unprocessable	Validation error (e.g., percentage > 100%)

Coupons API ​

List Coupons ​

Query Parameters ​

Example Request ​

Response ​

Get Single Coupon ​

Example Request ​

Response ​

Create Coupon ​

Request Body ​

Example Request ​

Response ​

Update Coupon ​

Request Body ​

Example Request ​

Response ​

Delete Coupon ​

Example Request ​

Response ​

Validate Coupon Code ​

Request Body ​

Cart Item Object ​

Example Request ​

Response (Valid Coupon) ​

Response (Invalid Coupon) ​

Toggle Coupon Status ​

Example Request ​

Response ​

Get Coupon Statistics ​

Example Request ​

Response ​

Get Coupon Usage History ​

Query Parameters ​

Example Request ​

Response ​

Duplicate Coupon ​

Example Request ​

Response ​

Coupon Object ​

Coupon Types ​

Validation Errors ​

API Errors ​

Coupons API

List Coupons

Query Parameters

Example Request

Response

Get Single Coupon

Example Request

Response

Create Coupon

Request Body

Example Request

Response

Update Coupon

Request Body

Example Request

Response

Delete Coupon

Example Request

Response

Validate Coupon Code

Request Body

Cart Item Object

Example Request

Response (Valid Coupon)

Response (Invalid Coupon)

Toggle Coupon Status

Example Request

Response

Get Coupon Statistics

Example Request

Response

Get Coupon Usage History

Query Parameters

Example Request

Response

Duplicate Coupon

Example Request

Response

Coupon Object

Coupon Types

Validation Errors

API Errors