Discovery call · clear quote within 48 hours

Official developer hub

DZN Soft Developers

Build apps that integrate with the DZN Soft commerce platform.

Connect your shipping, ERP, accounting, CRM, marketing or marketplace app to the dashboard merchants use every day, and let them install it in one click from the App Store.

API base URLhttps://api.dznsoft.com/v1
GET /v1/orders
curl https://api.dznsoft.com/v1/orders?status=new \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN"

{
  "data": [
    {
      "id": 5521,
      "number": "DZN-20260925-5521",
      "status": "new",
      "grand_total": 749.7
    }
  ],
  "meta": { "page": 1, "total": 1 }
}
  • OAuth 2.0

    Scoped access with the store owner’s explicit consent.

  • REST API

    Endpoints for products, orders, customers and inventory.

  • Webhooks

    Real-time event notifications signed with HMAC-SHA256.

  • Secure isolation

    Your code runs on your server; every store is separate.

Overview

DZN Soft Developers is the official developer hub for third-party apps that add shipping, ERP, accounting, CRM, messaging, marketplace, SEO, analytics and invoicing capabilities to stores.

Your app doesn’t run on DZN Soft servers. It lives on your own server and talks to a store through four controlled channels only: OAuth 2.0, the REST API, webhooks and sandboxed UI extensions. There is no access to the database, server files or any other store’s data.

  1. 1

    Create a developer account

    Sign up in the portal and turn on two-factor authentication.
  2. 2

    Create an app

    A Client ID and Client Secret are generated automatically; choose the scopes you need.
  3. 3

    Try it in a test store

    Install your app on a sandbox store filled with demo data and get an access token.
  4. 4

    Submit for review

    The DZN Soft team reviews security and quality; approved apps are published in the App Store.

Create a Developer Account

Use the developer sign-up page to create an account. A developer account is completely separate from your store (merchant) account; you can open both with the same email.

  • Passwords must be at least 10 characters and contain letters and numbers.
  • Turn on 2FA under Settings › Two-factor authentication with Google Authenticator, Microsoft Authenticator or 1Password. Keep your recovery codes somewhere safe.
  • The portal has Dashboard, Applications, API Credentials, Webhooks, Test Stores, API Logs, Documentation and Settings.

Create an App

In the portal, go to Applications › New application and enter the name, category (Shipping, ERP, Accounting, CRM, Marketing, SEO, AI, Inventory, Marketplace, Customer Service), description, icon and URLs.

FieldDescription
redirect_uriWhere the authorization code is sent. HTTPS is required (http://localhost is allowed for local testing). Must match exactly.
app_urlWhere the store owner lands after clicking "Install" in the App Store or "Open" in the dashboard. A ?store_id= parameter is added.
scopesThe permissions your app requests and the reason for each (shown on the consent screen).
privacy_urlPrivacy policy; required before you can submit for review.

The Client Secret is shown once

The Client Secret is displayed only once, when the app is created; DZN Soft stores it only as a hash. If you lose it, regenerate it from the API Credentials screen.

Using the API

All requests go to https://api.dznsoft.com/v1, over HTTPS, as JSON. Every request is authenticated with an access token bound to one store (tenant); the token decides whose data you touch, and no request parameter can change that.

TopicRule
FormatRequest and response bodies are application/json; dates are ISO 8601.
Paginationpage, per_page (1–100). Responses include meta.total and meta.last_page.
SyncingUse updated_since for incremental pulls; don’t fetch the full list over and over.
Error format{"error": {"code": "...", "message": "..."}}
CurrencyAmounts are decimal numbers in the store’s base currency (the currency field of each order).

Authentication

API requests are authenticated with the Authorization: Bearer <access_token> header. Access tokens start with dzn_at_, are valid for 1 hour and can only be obtained through the OAuth flow (or from the portal for your test store).

Every request goes through these checks, in order:

CheckOn failure
HTTPS403 https_required
Authentication — token valid, not expired, not revoked401 invalid_token / token_expired
Application — app approved and not suspended403 app_disabled
Store / Tenant — app installed on this store403 app_not_installed
Scope — permission present in both the token and the owner’s current approval403 insufficient_scope
Rate limit — per-minute and daily limits429 rate_limited
Authorization — the record belongs to the token’s store404 not_found

OAuth 2.0

Apps connect to stores with the OAuth 2.0 authorization code flow. PKCE (S256) is supported and recommended.

  1. 1

    Send the store owner to the consent screen

    Keep the state value in the session and compare it on return (CSRF protection).
  2. 2

    The store owner reviews and approves the permissions

    Each requested scope is listed with its description. Approval installs the app.
  3. 3

    Exchange the code for a token

    The code is single-use and valid for 10 minutes. The request must be made server to server.
1. Authorization URL
https://panel.dznsoft.com/oauth/authorize
  ?client_id=dzn_ci_xxxxxxxxxxxxxxxxxxxxxxxx
  &redirect_uri=https://your-app.com/oauth/callback
  &scope=products.read orders.read
  &state=RANDOM_SINGLE_USE_VALUE
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256
2. Callback
https://your-app.com/oauth/callback?code=AbC123...&state=RANDOM_SINGLE_USE_VALUE&store_id=812

3. Token request — POST https://api.dznsoft.com/oauth/token

curl -X POST "https://api.dznsoft.com/oauth/token" \
  -u "$DZN_CLIENT_ID:$DZN_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://your-app.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"
Response
{
  "token_type": "Bearer",
  "access_token": "dzn_at_…",
  "expires_in": 3600,
  "refresh_token": "dzn_rt_…",
  "scope": "products.read orders.read",
  "store_id": 812
}

Refreshing: when the access token expires, renew it with grant_type=refresh_token. Refresh tokens are single-use (rotation): every refresh returns a new pair. If a used refresh token is sent again, it’s treated as a leak and every token derived from the same authorization is revoked.

Refreshing a token
curl -X POST "https://api.dznsoft.com/oauth/token" \
  -u "$DZN_CLIENT_ID:$DZN_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$DZN_REFRESH_TOKEN"

Revoking: send POST https://api.dznsoft.com/oauth/revoke with token in the body to revoke an access or refresh token (RFC 7009).

API Keys

KeyFormatLifetimeWhere to store it
Client IDdzn_ci_…PermanentNot secret; it appears in the authorization URL.
Client Secretdzn_cs_…Until regeneratedOnly on your server; never in a browser or mobile app.
Access tokendzn_at_…1 hourPer store (store_id), encrypted.
Refresh tokendzn_rt_…60 days, single-usePer store, encrypted.
Webhook secretwhsec_…Until regeneratedOn your server, for signature verification.

Secret rotation: when you regenerate the Client Secret from API Credentials, the old one is still accepted for 24 hours so you can update your server. If you suspect a leak, rotate it immediately and tell our support team.

Permissions / Scopes

Request only the permissions your app needs. A write scope does not include the read scope for the same resource; if you need both, request both.

ScopeWhat the store owner seesCovers
products.readView productsProduct name, price, SKU, images and category.
products.writeCreate and edit productsAdd new products and update product details and prices.
orders.readView ordersLine items, totals, shipping address and buyer contact details. Card details are never shared.
orders.writeUpdate order statusOrder status, carrier and tracking number.
customers.readView customersMember name, email, phone and address.
inventory.readView inventoryStock levels per product and per size.
inventory.writeUpdate inventoryIncrease, decrease or set stock levels.

New scope = new consent

If you add a scope to a published app, existing stores don’t get it automatically. The store owner sees a "Requests new permission" notice on the Installed Apps screen; once you restart the OAuth flow and get approval, the new token carries the new scope. pending_scopes in the GET /shop response lists permissions awaiting approval.

Products API

Read the store’s product catalog, add new products and update existing ones. Response fields come from a fixed allow-list; internal store fields are never exposed.

List products

GEThttps://api.dznsoft.com/v1/products

Returns products ordered by ID, paginated.

Required scope
products.read
Success response
200

Parameters

NameInTypeDescription
pagequeryintegerPage number (default 1).
per_pagequeryintegerRecords per page, 1–100 (default 25).
skuquerystringExact match on SKU.
qquerystringSearch in the product name.
is_activequerybooleanOnly published (true) or inactive (false) products.
updated_sincequeryISO 8601Products changed after this time (for syncing).

Request Example

curl -X GET "https://api.dznsoft.com/v1/products" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": [
    {
      "id": 1042,
      "name": "Cotton Basic T-Shirt",
      "slug": "cotton-basic-t-shirt",
      "sku": "TS-001",
      "barcode": "8690000000012",
      "brand": "DZN",
      "category_id": 12,
      "description": "Soft-touch, 100% cotton T-shirt.",
      "price": 349.9,
      "compare_at_price": 449.9,
      "vat_rate": 20,
      "is_active": true,
      "images": [
        "https://panel.dznsoft.com/storage/store/ts-001.webp"
      ],
      "inventory": {
        "product_id": 1042,
        "sku": "TS-001",
        "track_stock": true,
        "stock": 58,
        "in_stock": true,
        "variants": [
          {
            "label": "M",
            "stock": 20
          },
          {
            "label": "L",
            "stock": 38
          }
        ]
      },
      "created_at": "2026-09-20T10:15:00+03:00",
      "updated_at": "2026-09-25T08:40:00+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.

Retrieve a product

GEThttps://api.dznsoft.com/v1/products/{id}

Details of a single product. Sending another store’s product ID returns 404.

Required scope
products.read
Success response
200

Parameters

NameInTypeDescription
idrequiredpathintegerProduct ID.

Request Example

curl -X GET "https://api.dznsoft.com/v1/products/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": {
    "id": 1042,
    "name": "Cotton Basic T-Shirt",
    "slug": "cotton-basic-t-shirt",
    "sku": "TS-001",
    "barcode": "8690000000012",
    "brand": "DZN",
    "category_id": 12,
    "description": "Soft-touch, 100% cotton T-shirt.",
    "price": 349.9,
    "compare_at_price": 449.9,
    "vat_rate": 20,
    "is_active": true,
    "images": [
      "https://panel.dznsoft.com/storage/store/ts-001.webp"
    ],
    "inventory": {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    },
    "created_at": "2026-09-20T10:15:00+03:00",
    "updated_at": "2026-09-25T08:40:00+03:00"
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
404not_foundThe product doesn’t exist in this store.

Create a product

POSThttps://api.dznsoft.com/v1/products

Adds a new product. Products are created inactive by default; send is_active: true to publish immediately.

Required scope
products.write
Success response
201

Parameters

NameInTypeDescription
namerequiredbodystringProduct name (max 255).
pricerequiredbodynumberSelling price, in the store’s base currency.
skubodystringSKU; unique within the store.
compare_at_pricebodynumberPrice before discount (shown struck through).
stockbodyintegerInitial stock.
category_idbodyintegerA category that belongs to the same store.
vat_ratebodyintegerTax rate: 0, 1, 8, 10, 18, 20.
is_activebodybooleanWhether the product is published.

Request Example

curl -X POST "https://api.dznsoft.com/v1/products" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cotton Basic T-Shirt","sku":"TS-001","price":349.9,"stock":58,"vat_rate":20,"is_active":true}'

Response Example

HTTP 201
{
  "data": {
    "id": 1042,
    "name": "Cotton Basic T-Shirt",
    "slug": "cotton-basic-t-shirt",
    "sku": "TS-001",
    "barcode": "8690000000012",
    "brand": "DZN",
    "category_id": 12,
    "description": "Soft-touch, 100% cotton T-shirt.",
    "price": 349.9,
    "compare_at_price": 449.9,
    "vat_rate": 20,
    "is_active": true,
    "images": [
      "https://panel.dznsoft.com/storage/store/ts-001.webp"
    ],
    "inventory": {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    },
    "created_at": "2026-09-20T10:15:00+03:00",
    "updated_at": "2026-09-25T08:40:00+03:00"
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
422validation_failedField error; details are in fields.

Update a product

PATCHhttps://api.dznsoft.com/v1/products/{id}

Only the fields you send are changed. Price and content changes trigger the product.updated webhook.

Required scope
products.write
Success response
200

Parameters

NameInTypeDescription
idrequiredpathintegerProduct ID.
pricebodynumberNew price.
compare_at_pricebodynumberStruck-through price.
is_activebodybooleanPublishing status.

Request Example

curl -X PATCH "https://api.dznsoft.com/v1/products/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"price":329.9,"compare_at_price":449.9}'

Response Example

HTTP 200
{
  "data": {
    "id": 1042,
    "name": "Cotton Basic T-Shirt",
    "slug": "cotton-basic-t-shirt",
    "sku": "TS-001",
    "barcode": "8690000000012",
    "brand": "DZN",
    "category_id": 12,
    "description": "Soft-touch, 100% cotton T-shirt.",
    "price": 329.9,
    "compare_at_price": 449.9,
    "vat_rate": 20,
    "is_active": true,
    "images": [
      "https://panel.dznsoft.com/storage/store/ts-001.webp"
    ],
    "inventory": {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    },
    "created_at": "2026-09-20T10:15:00+03:00",
    "updated_at": "2026-09-25T08:40:00+03:00"
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
404not_foundThe product doesn’t exist in this store.
422validation_failedField error.

Orders API

Read orders and update their fulfillment fields (status, carrier, tracking number). Amounts, payment status and buyer details can’t be changed through the API. Card numbers and CVVs are never stored and never appear in any response.

List orders

GEThttps://api.dznsoft.com/v1/orders

Returns orders newest first, paginated.

Required scope
orders.read
Success response
200

Parameters

NameInTypeDescription
pagequeryintegerPage number (default 1).
per_pagequeryintegerRecords per page, 1–100 (default 25).
statusquerystringnew, processing, shipped, completed, cancelled.
payment_statusquerystringpending, paid, refunded…
created_sincequeryISO 8601Orders created after this time.
updated_sincequeryISO 8601Orders changed after this time.

Request Example

curl -X GET "https://api.dznsoft.com/v1/orders" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": [
    {
      "id": 5521,
      "number": "DZN-20260925-5521",
      "status": "processing",
      "payment_status": "paid",
      "payment_method": "Credit card",
      "currency": "TRY",
      "subtotal": 699.8,
      "discount_total": 0,
      "shipping_total": 49.9,
      "grand_total": 749.7,
      "customer_id": 311,
      "customer": {
        "name": "Emma Wilson",
        "email": "emma@example.com",
        "phone": "+1 555 010 0000"
      },
      "shipping_address": {
        "address": "120 Example Street, Apt 4",
        "city": "New York",
        "district": "Brooklyn"
      },
      "lines": [
        {
          "product_id": 1042,
          "name": "Cotton Basic T-Shirt",
          "sku": "TS-001",
          "quantity": 2,
          "price": 349.9,
          "variants": [
            "Size: M"
          ]
        }
      ],
      "carrier": null,
      "tracking_number": null,
      "created_at": "2026-09-25T09:12:44+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.

Retrieve an order

GEThttps://api.dznsoft.com/v1/orders/{id}

Details of a single order.

Required scope
orders.read
Success response
200

Parameters

NameInTypeDescription
idrequiredpathintegerOrder ID.

Request Example

curl -X GET "https://api.dznsoft.com/v1/orders/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": {
    "id": 5521,
    "number": "DZN-20260925-5521",
    "status": "processing",
    "payment_status": "paid",
    "payment_method": "Credit card",
    "currency": "TRY",
    "subtotal": 699.8,
    "discount_total": 0,
    "shipping_total": 49.9,
    "grand_total": 749.7,
    "customer_id": 311,
    "customer": {
      "name": "Emma Wilson",
      "email": "emma@example.com",
      "phone": "+1 555 010 0000"
    },
    "shipping_address": {
      "address": "120 Example Street, Apt 4",
      "city": "New York",
      "district": "Brooklyn"
    },
    "lines": [
      {
        "product_id": 1042,
        "name": "Cotton Basic T-Shirt",
        "sku": "TS-001",
        "quantity": 2,
        "price": 349.9,
        "variants": [
          "Size: M"
        ]
      }
    ],
    "carrier": null,
    "tracking_number": null,
    "created_at": "2026-09-25T09:12:44+03:00"
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
404not_foundThe order doesn’t exist in this store.

Update order status

PATCHhttps://api.dznsoft.com/v1/orders/{id}

Shipping apps write tracking details here after creating a shipment. When an order moves to shipped, the buyer receives a shipping email.

Required scope
orders.write
Success response
200

Parameters

NameInTypeDescription
idrequiredpathintegerOrder ID.
statusbodystringnew, processing, shipped, completed, cancelled.
carrierbodystringCarrier name.
tracking_numberbodystringTracking number.
tracking_urlbodyhttps URLTracking page URL.

Request Example

curl -X PATCH "https://api.dznsoft.com/v1/orders/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"shipped","carrier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"https://carrier.example.com/1Z999AA10123456784"}'

Response Example

HTTP 200
{
  "data": {
    "id": 5521,
    "number": "DZN-20260925-5521",
    "status": "shipped",
    "payment_status": "paid",
    "payment_method": "Credit card",
    "currency": "TRY",
    "subtotal": 699.8,
    "discount_total": 0,
    "shipping_total": 49.9,
    "grand_total": 749.7,
    "customer_id": 311,
    "customer": {
      "name": "Emma Wilson",
      "email": "emma@example.com",
      "phone": "+1 555 010 0000"
    },
    "shipping_address": {
      "address": "120 Example Street, Apt 4",
      "city": "New York",
      "district": "Brooklyn"
    },
    "lines": [
      {
        "product_id": 1042,
        "name": "Cotton Basic T-Shirt",
        "sku": "TS-001",
        "quantity": 2,
        "price": 349.9,
        "variants": [
          "Size: M"
        ]
      }
    ],
    "carrier": "UPS",
    "tracking_number": "1Z999AA10123456784",
    "created_at": "2026-09-25T09:12:44+03:00"
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
404not_foundThe order doesn’t exist in this store.
422validation_failedInvalid status or URL.

Customers API

Read the customers who have registered with the store. Passwords, sessions and social sign-in identities never appear in any response.

List customers

GEThttps://api.dznsoft.com/v1/customers

Returns members in sign-up order, paginated.

Required scope
customers.read
Success response
200

Parameters

NameInTypeDescription
pagequeryintegerPage number (default 1).
per_pagequeryintegerRecords per page, 1–100 (default 25).
emailquerystringExact match on email.
created_sincequeryISO 8601Members who signed up after this time.

Request Example

curl -X GET "https://api.dznsoft.com/v1/customers" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": [
    {
      "id": 311,
      "name": "Emma Wilson",
      "email": "emma@example.com",
      "phone": "+1 555 010 0000",
      "address": "120 Example Street, Apt 4",
      "city": "New York",
      "district": "Brooklyn",
      "accepts_marketing": true,
      "is_active": true,
      "created_at": "2026-08-02T14:01:10+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.

Retrieve a customer

GEThttps://api.dznsoft.com/v1/customers/{id}

Details of a single member.

Required scope
customers.read
Success response
200

Parameters

NameInTypeDescription
idrequiredpathintegerCustomer ID.

Request Example

curl -X GET "https://api.dznsoft.com/v1/customers/1042" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": {
    "id": 311,
    "name": "Emma Wilson",
    "email": "emma@example.com",
    "phone": "+1 555 010 0000",
    "address": "120 Example Street, Apt 4",
    "city": "New York",
    "district": "Brooklyn",
    "accepts_marketing": true,
    "is_active": true,
    "created_at": "2026-08-02T14:01:10+03:00"
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
404not_foundThe customer doesn’t exist in this store.

Inventory API

Read and update stock levels. For products tracked by size, operations apply per variant. Updates use row locking, so two simultaneous adjustments never overwrite each other.

List inventory

GEThttps://api.dznsoft.com/v1/inventory

Total stock and the per-size breakdown for each product.

Required scope
inventory.read
Success response
200

Parameters

NameInTypeDescription
pagequeryintegerPage number (default 1).
per_pagequeryintegerRecords per page, 1–100 (default 25).
skuquerystringExact match on SKU.
low_stockquerybooleanOnly items below the low-stock threshold.

Request Example

curl -X GET "https://api.dznsoft.com/v1/inventory" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Example

HTTP 200
{
  "data": [
    {
      "product_id": 1042,
      "sku": "TS-001",
      "track_stock": true,
      "stock": 58,
      "in_stock": true,
      "variants": [
        {
          "label": "M",
          "stock": 20
        },
        {
          "label": "L",
          "stock": 38
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.

Adjust inventory

POSThttps://api.dznsoft.com/v1/inventory/adjust

adjust is a relative change (+5, −2); set is an absolute value. Stock never goes below zero. Changes trigger the inventory.updated webhook.

Required scope
inventory.write
Success response
200

Parameters

NameInTypeDescription
product_idbodyintegerProduct ID (or sku).
skubodystringSKU (or product_id).
variantbodystringSize name; required for products tracked by size.
adjustbodyintegerRelative change (don’t send together with set).
setbodyintegerAbsolute stock level.
reasonbodystringNote written to the audit log.

Request Example

curl -X POST "https://api.dznsoft.com/v1/inventory/adjust" \
  -H "Authorization: Bearer $DZN_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"sku":"TS-001","variant":"M","adjust":-2,"reason":"ERP sync"}'

Response Example

HTTP 200
{
  "data": {
    "product_id": 1042,
    "sku": "TS-001",
    "track_stock": true,
    "stock": 56,
    "in_stock": true,
    "variants": [
      {
        "label": "M",
        "stock": 18
      },
      {
        "label": "L",
        "stock": 38
      }
    ]
  }
}

Error Codes

HTTPCodeDescription
401invalid_tokenThe token is missing, invalid or revoked.
401token_expiredThe access token has expired; renew it with your refresh_token.
403insufficient_scopeThe token, or the store owner’s approval, doesn’t include the required permission.
429rate_limitedThe per-minute request limit was exceeded.
404not_foundThe product doesn’t exist in this store.
404variant_not_foundSize not found.
422variant_requiredThis product’s stock is tracked by size.

Webhooks

When an event happens in a store, a signed POST request is sent to the URL you subscribed. Webhooks are delivered from a queue; requests that don’t get a 2xx are retried at increasing intervals (1 min, 5 min, 30 min, 2 h, 6 h), 6 attempts in total.

EventRequired scopeWhen
order.createdorders.readA new order was created (storefront, dashboard or marketplace).
order.paidorders.readThe order’s payment was confirmed.
order.cancelledorders.readThe order was cancelled.
product.createdproducts.readA new product was added.
product.updatedproducts.readProduct details or price changed.
customer.createdcustomers.readA new member signed up with the store.
inventory.updatedinventory.readProduct or size stock changed.
app.uninstalled—The store owner uninstalled the app; tokens were revoked.

To receive an event, your app must hold that event’s scope in the store.

Request headers
POST /webhooks/dznsoft HTTP/1.1
Content-Type: application/json
User-Agent: DZNSoft-Webhooks/1.0
X-DZN-Event: order.created
X-DZN-Delivery: 7f2c1d7e-2a8b-4a55-9d0e-2f1d3c4b5a69
X-DZN-Store-Id: 812
X-DZN-Timestamp: 1790409600
X-DZN-Signature: t=1790409600,v1=5f8a…c21e
Body
{
  "id": "7f2c1d7e-2a8b-4a55-9d0e-2f1d3c4b5a69",
  "event": "order.created",
  "created_at": "2026-09-25T09:12:45+03:00",
  "store_id": 812,
  "sandbox": false,
  "data": {
    "id": 5521,
    "number": "DZN-20260925-5521",
    "status": "new",
    "grand_total": 749.7
  }
}

Verifying the signature (HMAC-SHA256)

v1 = HMAC_SHA256(webhook_secret, "<t>.<raw body>"). Compare in constant time and reject timestamps older than 5 minutes.

import crypto from "node:crypto";

// Read the body as raw text; the signature won’t match after JSON.parse.
export function verifyDznWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(parts.t);

  // Reject requests older than 5 minutes (replay protection).
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

URL rules

The webhook URL must be a public HTTPS address (port 443 or 8443). localhost, private networks (10.x, 192.168.x, 172.16–31.x), cloud metadata (169.254.x) and redirecting URLs are rejected. The same X-DZN-Delivery may arrive twice, so make your handler idempotent.

App Installation

  1. 1

    The store owner clicks "Install app" in the App Store

    The dashboard sends them to your app_url with ?store_id=812&source=dznsoft_app_store.
  2. 2

    Your app starts the OAuth flow

    Redirect to https://panel.dznsoft.com/oauth/authorize with your own state value (if you pass store_id, that store is preselected).
  3. 3

    The owner approves and installation completes

    You receive the code and exchange it for a token. The store sees your app on the Installed Apps screen.
  4. 4

    Uninstalling

    When the owner uninstalls your app, tokens are revoked immediately and the app.uninstalled webhook is sent. Delete that store’s data.

App Store Guidelines

Apps can’t be published directly. Statuses:

StatusMeaning
draftDraft; works only in your own test stores.
submittedSubmitted for review.
reviewBeing reviewed by the DZN Soft team.
approvedApproved; live in the App Store.
rejectedRejected; address the review note and resubmit.
suspendedSuspended; API access, tokens and webhooks are disabled.
  • Request only the scopes you actually use, and explain why.
  • A privacy policy, a support email and a working redirect URL are required.
  • Never ask for card numbers, CVVs or dashboard passwords, and never send store owners to a payment page outside DZN Soft.
  • Use store data only for your app’s purpose, don’t share it with third parties, and delete it when your app is uninstalled.
  • Changes to a published app go through review again; existing installations keep working in the meantime.
  • If there’s a security incident, DZN Soft can disable an app in one step: API access is cut, all tokens are revoked, webhooks stop and the app is removed from the App Store.

Test / Sandbox

Don’t test on real customer data. In the portal, Test Stores › Create test store opens a store that belongs only to you, filled with demo products, members and orders (up to 3). Example storefront URL: demo-a1b2c.sandbox.dznsoft.com.

  • "Install app + get token" installs your draft app on the test store without waiting for review and generates an access token.
  • Webhook bodies from test stores include "sandbox": true.
  • Test stores don’t take payments, aren’t billed, and all test data is removed when the store is deleted.

UI Extensions

Apps can’t modify the core Next.js or Laravel code. They can only add widgets to the fixed slots below, running in a sandboxed iframe. The widget URL must be public HTTPS and is checked separately during app review.

SlotLocation
product.after_priceProduct page — below the price
product.after_descriptionProduct page — below the description
cart.before_checkoutCart — above the checkout button
admin.order.sidebarDashboard — order detail sidebar

The iframe loads with sandbox="allow-scripts allow-forms allow-popups", so it can’t reach the page’s cookies, DOM or session. store_id and, depending on context, product_id/order_id are added to the widget URL; if you need data, fetch it through the API from your own server.

Gradual rollout

Extension slots are declared in the app form and checked during review; display in the storefront and dashboard is being enabled in stages. Follow the Changelog for announcements.

Error Codes

API errors use the {"error": {"code", "message"}} format; OAuth endpoints return {"error", "error_description"} as the standard requires.

HTTPCodeDescription
400invalid_request / invalid_grantThe OAuth request is incomplete, or the code/refresh token is invalid.
401unauthenticatedNo Authorization header.
401invalid_tokenThe token is invalid or revoked.
401token_expiredThe access token has expired.
401invalid_clientWrong client_id or client_secret.
403insufficient_scopeMissing permission (see the required_scope field).
403app_not_installedThe app was uninstalled from this store.
403app_disabledThe app hasn’t been approved yet, or was suspended by DZN Soft.
403https_requiredThe request must be made over HTTPS.
404not_foundThe record doesn’t exist in this store.
422validation_failedInput validation failed; the fields property lists the invalid fields.
429rate_limited / daily_limit_exceededRequest limit exceeded; wait for Retry-After.
503unavailableThe service is temporarily unavailable.

Rate Limits

LimitValueApplies to
Per minute120 requestsPer app × store (installation)
Daily50,000 requestsPer app × store
Token endpoint30 requests / minutePer IP

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers. When you hit the limit you get a 429 with Retry-After (seconds); wait that long and retry with exponential backoff.

Security

MeasureHow it works
Code isolationThird-party code never runs on DZN Soft servers; there’s no PHP/Node/shell execution and no database, .env or file access.
Tenant isolationThe store is determined only by the access token; every query is scoped to that store.
IDOR protectionIDs belonging to another store return 404; their existence isn’t even confirmed.
OAuth 2.0 + PKCEExact redirect_uri matching, mandatory state, single-use 10-minute codes.
Token securityTokens are stored only as SHA-256 hashes; short lifetimes, rotation, instant revocation.
HMAC webhooksTimestamped SHA-256 signatures with replay protection.
SSRF protectionWebhook/widget URLs can’t resolve to private networks; connections are pinned to the verified IP and redirects aren’t followed.
Card dataCard numbers and CVVs are never stored and never appear in any API response.
Audit logInstalls, permissions, keys, reviews and API writes are recorded in the audit log.
Account security2FA (TOTP) and recovery codes for developer accounts.
Browser securityCSP, X-Frame-Options and HSTS; the consent screen can’t be framed by other sites.

Reporting a vulnerability

If you find a security vulnerability, report it to info@dznsoft.com before sharing it publicly.

Changelog

  1. v1.0September 26, 2026
    • Public API v1: Products, Orders, Customers and Inventory endpoints.
    • OAuth 2.0 authorization code flow, PKCE (S256), refresh token rotation.
    • HMAC-SHA256 signed webhooks with automatic retries.
    • Developer portal, test stores (sandbox) and App Store review.

Portal: panel.dznsoft.com/developer