These four endpoints manage the store's promo codes, the codes buyers type at checkout to lower what they pay. They work on the same codes as the promo codes page of the dashboard, described in Discount codes, and they can also rename a code, which the dashboard cannot.

A code takes its discount off the products subtotal, never off shipping. A percentage code takes that share of the subtotal. A fixed code subtracts its amount in DZD and never takes off more than the subtotal. A code cannot be limited to a product, a category or a customer, cannot cap the discount on a large cart, and cannot give free shipping.

Before you start

The Promo codes add-on must be active on the store (/dashboard/addons). The list works without it and tells you in addon_enabled. Every write answers 409 addon_inactive until the add-on is on, and buyers cannot use any code at checkout while it is off.
The key needs the promo scopes. Keys created from the dashboard (/dashboard/api) get both. Scopes are frozen when a key is created, so a key that lacks them answers 403 forbidden: create a new key from the dashboard.
starts_at and expires_at are in Algeria time, in the form YYYY-MM-DD HH:MM:SS.

Scope	Description
`promos:read`	Read promo codes.
`promos:write`	Create, update and delete promo codes. This changes the prices your buyers pay.

The promo code object

Field	Type	Meaning
`id`	int	The code's id in the store.
`code`	string	What buyers type. Upper case, `A-Z`, `0-9`, `-` and `_`, unique in the store.
`discount_type`	string	`percentage` or `fixed`.
`discount_value`	number	The percentage (above 0, at most 100) or the amount in DZD.
`min_order_amount`	number or null	The products subtotal an order must reach for the code to apply. `null` means no minimum.
`max_uses`	int or null	How many orders can use the code. `null` means unlimited.
`used_count`	int	How many orders have used it. Read-only.
`is_active`	bool	An inactive code is refused at checkout.
`starts_at`	string or null	Before this time the code is refused. `null` means it works right away.
`expires_at`	string or null	After this time the code is refused. `null` means it never expires.
`created_at`, `updated_at`	string	`YYYY-MM-DD HH:MM:SS`, server time.

GET /v1/promo-codes

The store's codes, newest first. There is no call that reads a single code by id: page through this list.

Auth: platform key with promos:read.

Query parameters

Param	Type	Default	Notes
`is_active`	string	none	`true`, `1`, `yes` or `on` returns the active codes. Any other value returns the inactive ones. Leave it out for all codes.
`limit`	int	50	1 to 200.
`cursor`	string	none	`next_cursor` of the previous page. See Pagination.

Request

curl 'https://api.dzbuild.app/v1/promo-codes?is_active=true' \
  -H "Authorization: Bearer $DZ_KEY"

Response 200

{
  "data": {
    "items": [
      {
        "id": 20,
        "code": "WELCOME10",
        "discount_type": "percentage",
        "discount_value": 10,
        "min_order_amount": 3000,
        "max_uses": 100,
        "used_count": 7,
        "is_active": true,
        "starts_at": null,
        "expires_at": "2026-11-30 23:59:00",
        "created_at": "2026-10-06 14:20:11",
        "updated_at": "2026-10-06 14:20:11"
      }
    ],
    "next_cursor": null,
    "has_more": false,
    "addon_enabled": true
  }
}

addon_enabled says whether the Promo codes add-on is active. When it is false, the list still answers, but writes fail and buyers cannot use the codes.

POST /v1/promo-codes

Creates a code. It works at checkout as soon as it is created, unless you send is_active: false or a later starts_at.

Auth: platform key with promos:write. Requires Idempotency-Key.

Body

Field	Type	Required	Notes
`code`	string	yes	Spaces around it are removed and letters are upper-cased, then it must be 2 to 30 characters of `A-Z`, `0-9`, `-` or `_`. A code that already exists in the store answers `409 code_exists`.
`discount_type`	string	yes	`percentage` or `fixed`, in any case. There is no default.
`discount_value`	number	yes	Above 0. At most 100 for `percentage`, and 100 needs the merchant's confirmation (see the section on 100% discounts below). No upper limit for `fixed`.
`min_order_amount`	number or null	no	Minimum products subtotal in DZD. `0`, `""` or `null` means no minimum.
`max_uses`	int or null	no	1 or more. `0`, `""` or `null` means unlimited.
`is_active`	bool	no	Defaults to `true`. Send a JSON boolean: a string such as `"false"` is read as `true`.
`starts_at`	string or null	no	A common date-time form, such as `2026-11-01 08:00` or an ISO 8601 string. Stored as `YYYY-MM-DD HH:MM:SS` in Algeria time; a value with a UTC offset is converted. `null` or `""` means no start date.
`expires_at`	string or null	no	Same forms. It must be in the future and after `starts_at`. `null` or `""` means no expiry.
`confirm_token`	string	no	Only for a 100% discount.
`confirm_full_discount`	bool	no	Only for a 100% discount.

Request

curl -X POST 'https://api.dzbuild.app/v1/promo-codes' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promo-welcome10-create" \
  -d '{"code": "welcome10", "discount_type": "percentage", "discount_value": 10, "min_order_amount": 3000, "max_uses": 100, "expires_at": "2026-11-30 23:59"}'

Response 201

{
  "data": {
    "id": 20,
    "code": "WELCOME10",
    "discount_type": "percentage",
    "discount_value": 10,
    "min_order_amount": 3000,
    "max_uses": 100,
    "used_count": 0,
    "is_active": true,
    "starts_at": null,
    "expires_at": "2026-11-30 23:59:00",
    "created_at": "2026-10-06 14:20:11",
    "updated_at": "2026-10-06 14:20:11"
  }
}

PATCH /v1/promo-codes/{id}

Changes only the fields you send, with the same rules as the create. A field you leave out keeps its value.

Auth: platform key with promos:write. Requires Idempotency-Key.

code can be changed. The new text must be free in the store, otherwise the call answers 409 code_exists.
discount_type and discount_value are checked as a pair. Sending only discount_type: "percentage" on a 500 DZD fixed code answers 422 invalid_discount_value, because 500 is above 100. Send both.
A new expires_at must be in the future. A code that has already expired stays editable as long as you do not send expires_at.
used_count cannot be written.
An empty body changes nothing and returns the code.
A code of another store answers 404, like a code that does not exist.

Request

curl -X PATCH 'https://api.dzbuild.app/v1/promo-codes/20' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promo-20-extend" \
  -d '{"max_uses": 200, "expires_at": "2026-12-31 23:59"}'

Response 200

{
  "data": {
    "id": 20,
    "code": "WELCOME10",
    "discount_type": "percentage",
    "discount_value": 10,
    "min_order_amount": 3000,
    "max_uses": 200,
    "used_count": 7,
    "is_active": true,
    "starts_at": null,
    "expires_at": "2026-12-31 23:59:00",
    "created_at": "2026-10-06 14:20:11",
    "updated_at": "2026-10-20 09:05:42"
  }
}

DELETE /v1/promo-codes/{id}

Deletes the code, so buyers can no longer use it. Orders already placed with it keep their discount. To pause a code without losing its usage count, send is_active: false with PATCH instead.

Auth: platform key with promos:write. Requires Idempotency-Key.

Request

curl -X DELETE 'https://api.dzbuild.app/v1/promo-codes/20' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: promo-20-delete"

Response 200

{
  "data": {
    "deleted": true,
    "id": 20
  }
}

100% discounts

A percentage code at 100 makes the goods free for every buyer who has the code. A create, or an update that sends discount_type or discount_value, is not written on the first call when the result is a 100% percentage code:

The call answers 422 confirmation_required and writes nothing. The error carries confirm_token (single use, valid 600 seconds), action and will_change, a summary to show the merchant.
Once the merchant approves, repeat the same body with confirm_token added and a new Idempotency-Key (the first key is bound to the body without the token). A token that expired, was already used, or no longer matches the request answers 422 confirmation_stale with a fresh token.

With a key created from the dashboard you can skip the round trip by sending confirm_full_discount: true in the first call. The DZBuild Copilot cannot use that flag and always goes through the token.

{
  "error": {
    "code": "confirmation_required",
    "message": "A 100% discount makes every order free ...",
    "confirm_token": "cft_xxxxxxxxxxxxxxxx",
    "confirm_token_expires_in": 600,
    "action": "promo.full_discount:new",
    "will_change": {
      "action": "Create a promo code that makes orders free",
      "code": "FREEGIFT",
      "discount": "100% off the whole order subtotal",
      "reversible": true,
      "note": "Any customer with this code pays 0 for the goods. Orders already placed with it cannot be reversed by deleting the code."
    }
  }
}

On an update, action ends with the code's id instead of new, and will_change.action reads Change promo code #20 to make orders free.

curl -X POST 'https://api.dzbuild.app/v1/promo-codes' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promo-freegift-approved" \
  -d '{"code": "FREEGIFT", "discount_type": "percentage", "discount_value": 100, "max_uses": 1, "confirm_token": "cft_REPLACE_WITH_TOKEN"}'

Change history and undo

Every create, update and delete made through the API is recorded. Codes changed on the dashboard page are not recorded, so they cannot be undone through the API.

GET /v1/changes?entity=promo_code lists the promo code changes, newest first, with store:read. Each item carries the change id, the code's id as entity_id, the action (create, update or delete) and a summary.
POST /v1/changes/{id}/undo needs promos:write, an Idempotency-Key and the add-on active, like any write.
Undoing an update puts the earlier values back, with no confirmation, even a 100% discount or an expiry date that has passed. If the code was deleted since, the undo answers 422 restore_target_missing.
Undoing a delete re-creates the code with its usage count, and keeps its id when that id is still free.
Undoing a create answers 422 nothing_to_restore: delete the code instead.
An installed app's token cannot read or undo changes: both answer 403 forbidden.

curl -X POST 'https://api.dzbuild.app/v1/changes/500/undo' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: undo-500"

{
  "data": {
    "undone": true,
    "change_id": 500,
    "entity": "promo_code",
    "undo_change_id": 510
  }
}

A change undone a second time answers 409 already_undone.

Errors

HTTP	Code	Cause
400	`bad_request`	The id in the path is not all digits, the body is not valid JSON, or `Idempotency-Key` is missing or malformed.
403	`forbidden`	`Missing scope: promos:read` or `Missing scope: promos:write`, or `API access requires an active Enterprise plan` for a merchant key whose store is not on an active Enterprise plan.
404	`not_found`	No promo code with this id in the store.
409	`addon_inactive`	The Promo codes add-on is not active on the store. Writes only.
409	`code_exists`	Another code of the store already has this text.
422	`invalid_code`	`code` is shorter than 2 or longer than 30 characters, or has a character other than `A-Z`, `0-9`, `-` and `_`.
422	`invalid_discount_type`	`discount_type` is missing, or is not `percentage` or `fixed`.
422	`invalid_discount_value`	`discount_value` is missing, not a number, 0 or less, or above 100 for `percentage`.
422	`invalid_min_order_amount`	`min_order_amount` is not a number.
422	`invalid_max_uses`	`max_uses` is not a number, or is below 1.
422	`invalid_starts_at`, `invalid_expires_at`	The date cannot be read.
422	`expires_at_in_past`	The `expires_at` you sent is not in the future.
422	`invalid_date_window`	`expires_at` is not after `starts_at`.
422	`confirmation_required`, `confirmation_stale`	A 100% discount waits for the merchant's approval. See the section above.
422	`idempotency_key_reuse`	The same `Idempotency-Key` was used with a different body or path.
500	`server_error`	The write failed. Retry with the same `Idempotency-Key`.

A 4xx answer is stored with its Idempotency-Key for 24 hours and replayed to a retry with the same body. After you activate the add-on or fix the body, send the call with a new key. Errors that every endpoint shares, such as 401, 402 and 429, are in Errors, and the retry rules are in Idempotency.

Known limits

Uses can pass max_uses. When several buyers check out with the same code at the same moment, used_count can end above max_uses.
No webhook. Creating, changing or deleting a promo code sends no webhook event.