# Landing pages A landing page is a focused, single-product conversion page. They're independent of the storefront catalogue — you can have a landing page with no live product (for upcoming launches), or one tied to a specific product for paid ads. Sections (image carousels, order forms, fake visitors, countdowns, etc.) can be built through the API with the section endpoints below, or in the dashboard. ## Plan limits | Plan | Landing pages (all statuses — drafts count) | | ---------------------- | --------------------------------------------- | | Free | 0 (one-time purchase: 1000 DZD/lifetime each) | | Pro | 3 | | Unlimited / Enterprise | unlimited | The cap applies on every create path, the API included, and counts every landing page including drafts. `POST /v1/landing-pages` (and `POST /v1/landing-pages/generate`) on a store at its limit answers `403 limit_reached`. A Free-plan store can create a page only while it has an unused purchased slot; `POST /v1/landing-pages` marks that page `is_purchased: true`, which is what makes it visible on the storefront. ## `GET /v1/landing-pages` List landing pages. Cursor-paginated. Served fresh on every call, like `GET /v1/landing-pages/{id}`. **Auth:** platform key with `landing_pages:read`, which `GET /v1/landing-pages/{id}` needs too. A key without it gets `403 forbidden`. ### Query parameters | Param | Type | Notes | | -------- | ------------------- | ---------- | | `limit` | int 1–200 | Default 50 | | `cursor` | string | Opaque | | `status` | `active` \| `draft` | Filter | An unrecognised `status` is ignored, returning all pages rather than a `400`. ### Response 200 ``` { "data": { "items": [ { "id": 42, "title": "Black T-Shirt — 30% off", "slug": "black-tshirt-30-off", "public_url": "https://your-store.example.com/landing/black-tshirt-30-off", "status": "active", "language": "ar", "product_id": 26, "views": 1543, "is_purchased": false, "created_at": "2026-03-01 10:00:00", "updated_at": "2026-03-15 14:22:11" } ], "next_cursor": null, "has_more": false } } ``` ## `GET /v1/landing-pages/{id}` Detail with `section_count`. ``` { "data": { "id": 42, "title": "Black T-Shirt — 30% off", "slug": "black-tshirt-30-off", "public_url": "https://your-store.example.com/landing/black-tshirt-30-off", "status": "active", "language": "ar", "product_id": 26, "views": 1543, "is_purchased": false, "meta_title": "Black T-Shirt — Cotton 200gsm — 30% off | DZBuild", "meta_description": "Limited-time offer on our cotton black t-shirt.", "section_count": 7, "created_at": "2026-03-01 10:00:00", "updated_at": "2026-03-15 14:22:11" } } ``` ### Field reference | Field | Notes | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | Strict `active` or `draft` only — there is no `archived` state for landing pages. | | `language` | `ar`, `fr` or `en`. | | `public_url` | Live address of the page: the store's address (its custom domain once it is live, otherwise its subdomain), then `/landing/` and the slug. `null` while the store has no address. Use it as is rather than building the URL yourself. | | `product_id` | The linked product, or `null`. An order-taking section (`order_form`, `order_button`, `product_offers`) needs this or its own `settings.product_id`. Once set, PATCH can switch it to another product but not back to `null`. | | `views` | **Read-only.** Counted each time the public page is viewed; the API cannot write it and there is no way to reset it. | | `is_purchased` | `true` once the page has been bought outright (1000 DZD/lifetime). On the Free plan this is what makes the page visible on the storefront. | | `section_count` | Detail endpoint only — a live count of the page's sections, computed per request. | | `meta_title` / `meta_description` | SEO tags. See the note under create. | ## `POST /v1/landing-pages` — create **Auth:** platform key with `landing_pages:write` and `landing_pages:read`. The answer reads the page back, so with `landing_pages:write` alone the page is saved and the call answers `403 forbidden`; the same holds for PATCH and `/publish`. **Requires `Idempotency-Key`.** ### Body | Field | Type | Required | Notes | | ------------------ | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | string, 1 to 255 bytes | ✅ | The limit counts bytes, not letters: an Arabic letter takes 2 bytes, so an Arabic title tops out near 127 letters | | `slug` | string | | Auto-derived from `title` if omitted. A slug you supply here is stored **without** normalisation — send a clean one | | `status` | `active` \| `draft` | | Default `draft`. Any other value is silently coerced to `draft` | | `language` | `ar` \| `fr` \| `en` | | Default `ar`. Any other value is silently coerced to `ar` | | `product_id` | int | | Must belong to your store; the page links to this product | | `meta_title` | string ≤ 255 | | SEO title. Omit it via the API and it is stored and returned as `null` (unlike the dashboard form, which copies `title` into it). The public page still renders `title` as a fallback, so the visible page title is correct either way | | `meta_description` | string | | SEO description | Slugs are made unique within your store by appending `-2`, `-3`, … An empty slug base falls back to `landing-` plus 6 hex characters. ### Errors | Code | Cause | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `bad_request` "Body must be valid JSON" | Wrong Content-Type or malformed JSON | | `bad_request` "title is required (1-255 chars)" | Missing or over-long title | | `bad_request` "product\_id N does not belong to this store" | Cross-store id | | `limit_reached` (403) | The store is at its plan's landing page limit (drafts count). On Free: no unused purchased slot is left | ### Request ``` curl -X POST 'https://api.dzbuild.app/v1/landing-pages' \ -H "Authorization: Bearer $DZ_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "title": "Black T-Shirt — 30% off", "language": "ar", "product_id": 26, "status": "draft" }' ``` Returns **200** (not 201) and the same shape as `GET /v1/landing-pages/{id}`. The new landing page has no sections: add them with the section endpoints below. The publish check does not run on create, so create the page as a `draft` and publish it once its sections are in place; a page created with `status: active` goes live empty. ## `PATCH /v1/landing-pages/{id}` Partial update. PATCH validates more strictly than create: an invalid `status` returns `400 bad_request` ("status must be active or draft") and an invalid `language` returns `400` ("language must be ar, fr, or en") instead of being coerced. `title` must still be 1 to 255 bytes. A `slug` sent on PATCH **is** normalised, unlike on create. Setting `status` to `active` runs the publish check (see `/publish` below). Once a page has a product, `product_id: null` answers `422 product_required`; send another product id to switch products. ``` curl -X PATCH 'https://api.dzbuild.app/v1/landing-pages/42' \ -H "Authorization: Bearer $DZ_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "title": "Black T-Shirt — Spring promo" }' ``` Renaming auto-regenerates `slug` only if you didn't pass `slug` explicitly. When the slug changes, by a rename or explicitly, the old address keeps working and redirects to the new one. ## Sections A page renders its sections from top to bottom. Section reads need `landing_pages:read`, section writes need `landing_pages:write`, and every write needs an `Idempotency-Key`. | Endpoint | Body | Answer | | ----------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `GET /v1/landing-page-section-types` | | `200`: `section_types`, each a `type` with its `default_settings` | | `GET /v1/landing-pages/{id}/sections` | | `200`: `landing_page_id` and `sections` in render order (up to 500, not paginated) | | `POST /v1/landing-pages/{id}/sections` | `section_type` (or `type`), optional `settings` | `201`: the new `section`, added at the end of the page | | `POST /v1/landing-pages/{id}/sections/batch` | `sections`: up to 30 objects with `type` (or `section_type`) and optional `settings` | `201`: the new `sections`. All or nothing: one bad entry saves none | | `POST /v1/landing-pages/{id}/sections/reorder` | `sections`: every section id of the page, once each, in the new order | `200`: the sections in their new order | | `PATCH /v1/landing-pages/{id}/sections/{section_id}` | `settings`, optional `replace` | `200`: the updated `section` | | `DELETE /v1/landing-pages/{id}/sections/{section_id}` | | `200`: `{ "deleted": true, "id": 901, "landing_page_id": 42 }` | A section carries `id`, `section_type`, `sort_order` and `settings`. Answers that read the page back (the list, reorder and PATCH) also carry `created_at` and `updated_at`. The 14 types are `image`, `order_form`, `order_button`, `free_text`, `contact_button`, `countdown`, `fake_visitors`, `special_offer`, `price_display`, `product_offers`, `custom_form`, `image_carousel`, `announcement_bar` and `testimonials`. Read `GET /v1/landing-page-section-types` before writing, so your settings keys match what the page renders. * Settings you send are merged over the type's defaults, so one call can create a fully set up section. On PATCH they are merged over what is stored; send `"replace": true` to start again from the type's defaults. Nested objects merge key by key; lists such as `slides`, `items`, `offers` and `fields` are replaced whole. The section type cannot change. * An `order_form`, `order_button` or `product_offers` section needs a product: the page's `product_id` or its own `settings.product_id`. Without one the call answers `422 landing_page_has_no_product`. A `settings.product_id` from another store answers `422 validation_error`. * The order form fields `show_name`, `show_phone` and `show_wilaya` are always saved as `true` in any section that has them. * A `slides` list takes at most 20 entries and an `items` list at most 30 (`422 too_many_items`). Encoded settings may not pass 262144 bytes (`422 settings_too_large`). An unknown type answers `422 invalid_section_type`. * On a write, a page outside your store answers `404 landing_page_not_found` (the list and the check answer `404 not_found`), and a section that is not on the page answers `404 section_not_found`. A reorder list that repeats or leaves out a section answers `422 validation_error`. * Section changes appear in `GET /v1/changes`. An edit, a deletion or a reorder can be undone with `POST /v1/changes/{id}/undo`, and a deleted section that comes back through an undo gets a new id. Adding a section cannot be undone: delete it instead. ``` curl -X POST 'https://api.dzbuild.app/v1/landing-pages/42/sections/batch' \ -H "Authorization: Bearer $DZ_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "sections": [ { "type": "announcement_bar" }, { "type": "order_form" } ] }' ``` ## `GET /v1/landing-pages/{id}/check` Reports what a buyer would find broken on the page. **Auth:** `landing_pages:read`. The answer carries `landing_page_id`, `status`, `product_id`, `sections` (how many were checked), `publishable`, `blocked_by` (the first blocking message, or `null`) and `problems`. Each problem has `code`, `severity` (`blocking` or `warning`) and `message`; problems tied to one section also carry `section_id`. | Code | Severity | Meaning | | ---------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `empty_page` | `blocking` | The page has no sections, so it renders blank | | `order_form_without_product` | `blocking` | A section takes orders, but neither the page nor the section names a product, so orders would land at 0 DA | | `section_product_not_found` | `blocking` | A section points at a product that is not in your store | | `no_order_form` | `warning` | Nothing on the page can take an order | | `multiple_order_forms` | `warning` | More than one `order_form` or `order_button` renders | | `variants_need_page_product` | `warning` | A section names a product with variants while the page has no product. Variant pickers render only from the page's own product, so set `product_id` on the page | Publishing is refused while a blocking problem remains (see below). ## `POST /v1/landing-pages/{id}/publish` Convenience: flip status to `active`. Equivalent to `PATCH ... { status: "active" }`, and refused the same way: while `GET /v1/landing-pages/{id}/check` reports a blocking problem, the call answers `422 page_not_publishable` and the error carries the `problems` list. Edits that do not send `status` skip this check, even on a live page. ``` curl -X POST 'https://api.dzbuild.app/v1/landing-pages/42/publish' \ -H "Authorization: Bearer $DZ_KEY" \ -H "Idempotency-Key: publish-42-$(date +%s)" ``` ## `POST /v1/landing-pages/generate` Builds a landing page from one of your products with AI. It answers `202` at once with a task to poll; a run takes about two minutes. **Auth:** the `ai:generate` scope. Keys created in the dashboard or with `POST /v1/keys` and third-party apps do not carry it and get `403 forbidden`; Claude, ChatGPT and DZBuild Copilot connections carry it. **Requires `Idempotency-Key`.** | Field | Type | Required | Notes | | ------------- | -------------------- | -------- | --------------------------------------------------------------- | | `title` | string | ✅ | At least 3 characters; cut at 255 | | `product_id` | int | ✅ | An active product of your store with at least one image | | `description` | string | | Brief for the page, cut at 2000 characters | | `language` | `ar` \| `fr` \| `en` | | Default `ar` | | `size` | `medium` \| `tall` | | Default `medium`. `medium` costs 20 AI credits, `tall` costs 45 | The answer carries `task_id`, `size`, `credits_charged`, `eta_seconds` and `poll`. Credits are taken when the run starts and given back when the run fails or times out. Errors: `400 bad_request` (title missing or shorter than 3 characters), `402 quota_exceeded` (not enough AI credits), `403 limit_reached` (plan landing page limit, with `limit` and `current`), `409 already_processing` (one generation per store at a time), `422 product_required`, `product_not_found` or `product_has_no_image`, `429 rate_limited` or `too_many_concurrent`, `503 provider_unavailable` (no credits taken). Poll `GET /v1/landing-pages/generate/{task_id}` with `landing_pages:read`. It answers `task_id`, `status` (`processing` while the page is built, then `completed` or `failed`), `landing_page_id` once the page exists, `current_step` and `error`. A run still processing after 10 minutes is marked `failed` with error `timeout` at the next poll, and its credits are refunded. ## `DELETE /v1/landing-pages/{id}` Hard delete. The page's sections are removed with it. ``` curl -X DELETE 'https://api.dzbuild.app/v1/landing-pages/42' \ -H "Authorization: Bearer $DZ_KEY" \ -H "Idempotency-Key: del-42" ``` Response: `{ "data": { "deleted": true, "id": 42 } }`.