Discount Codes API

Manage discount codes for a site. A discount code applies a percentage off an
order at checkout.

Endpoints

• List Discount Codes - GET /api/v1/sites/{site_id}/discount-codes/
• Create Discount Code - POST /api/v1/sites/{site_id}/discount-codes/
• Get Discount Code - GET /api/v1/sites/{site_id}/discount-codes/{discount_code_id}/
• Update Discount Code - PUT /api/v1/sites/{site_id}/discount-codes/{discount_code_id}/
• Delete Discount Code - DELETE /api/v1/sites/{site_id}/discount-codes/{discount_code_id}/

Discount codes are scoped to a site. See Sites for the site
endpoints.

List Discount Codes

Retrieve the discount codes for a site, ordered by code.

Endpoint: GET /api/v1/sites/{site_id}/discount-codes/

Scope Required: discount_codes:read

Query Parameters

The response reports has_more, which is true when another page follows.
A malformed after or before, both at once, or an invalid limit returns
INVALID_REQUEST_ERROR.

Request

curl -X GET "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/discount-codes/?limit=20" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "dsc_d0b6fmv28q6vn14peun0",
      "code": "SUMMER10",
      "percentage": 10,
      "active": true,
      "usage_count": 3,
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ],
  "has_more": false
}

Create Discount Code

Create a discount code for a site. Codes are normalized to uppercase.

Endpoint: POST /api/v1/sites/{site_id}/discount-codes/

Scope Required: discount_codes:write

Request Body

{
  "code": "SUMMER10",
  "percentage": 10,
  "active": true
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/discount-codes/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "code": "SUMMER10",
    "percentage": 10,
    "active": true
  }'

Response

Status: 201 Created

{
  "id": "dsc_d0b6fmv28q6vn14peun0",
  "code": "SUMMER10",
  "percentage": 10,
  "active": true,
  "usage_count": 0,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Invalid code

Status: 400 Bad Request

{
  "error": "Code must be alphanumeric",
  "code": "INVALID_FIELD"
}

Invalid percentage

Status: 400 Bad Request

{
  "error": "Percentage must be between 1 and 100",
  "code": "INVALID_FIELD"
}

Duplicate code

Status: 409 Conflict

{
  "error": "Resource already exists",
  "code": "DUPLICATE"
}

Get Discount Code

Retrieve a single discount code.

Endpoint: GET /api/v1/sites/{site_id}/discount-codes/{discount_code_id}/

Scope Required: discount_codes:read

Request

curl -X GET "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/discount-codes/dsc_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "dsc_d0b6fmv28q6vn14peun0",
  "code": "SUMMER10",
  "percentage": 10,
  "active": true,
  "usage_count": 3,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Update Discount Code

Update a discount code. The full code, percentage, and active state are
required.

Endpoint: PUT /api/v1/sites/{site_id}/discount-codes/{discount_code_id}/

Scope Required: discount_codes:write

Request Body

{
  "code": "SUMMER20",
  "percentage": 20,
  "active": true
}

Request

curl -X PUT "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/discount-codes/dsc_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{
    "code": "SUMMER20",
    "percentage": 20,
    "active": true
  }'

Response

Status: 204 No Content

Delete Discount Code

Delete a discount code.

Endpoint: DELETE /api/v1/sites/{site_id}/discount-codes/{discount_code_id}/

Scope Required: discount_codes:write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/discount-codes/dsc_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Discount Code Object

Fields