DealNear Merchant API v1

Authentication

Authorization: Bearer dn_your_secret_key

Give each key only the permissions it needs. A key without the required permission gets 403 with "error": "missing_scope".

Try your key:

curl https://www.dealnear.ca/api/v1/me \
  -H "Authorization: Bearer $DEALNEAR_API_KEY"

Redeeming at checkout

The most common integration: the customer shows their coupon code, your till looks it up and redeems it. This needs a key with coupons:read and coupons:redeem. Codes can be sent however the cashier typed them — dn7k4mq2xp works as well as DN-7K4M-Q2XP.

1. Look up the code (optional)

Shows the cashier which deal it is for, and whether it can be used (is_usable).

curl https://www.dealnear.ca/api/v1/coupons/DN-7K4M-Q2XP \
  -H "Authorization: Bearer $DEALNEAR_API_KEY"

2. Redeem it

curl -X POST https://www.dealnear.ca/api/v1/coupons/DN-7K4M-Q2XP/redeem \
  -H "Authorization: Bearer $DEALNEAR_API_KEY"

200 OK

{
  "data": {
    "code": "DN-7K4M-Q2XP",
    "status": "redeemed",
    "is_usable": false,
    "deal": { "id": 42, "title": "Hot pot for two, 20% off", "discount_label": "20% off" },
    "customer": { "name": "Jamie" },
    "claimed_at": "2026-10-12T18:04:11-04:00",
    "redeemed_at": "2026-10-15T12:31:09-04:00",
    "expires_at": "2026-11-15T23:59:59-05:00",
    "updated_at": "2026-10-15T12:31:09-04:00"
  }
}

A coupon can only be redeemed once, so it is safe to retry after a network error: a repeat returns 409 with the coupon and when it was redeemed. Tell the cashier why based on error:

Creating deals

curl -X POST https://www.dealnear.ca/api/v1/deals \
  -H "Authorization: Bearer $DEALNEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "en",
    "content": {
      "en":    { "title": "Hot pot for two, 20% off", "discount_label": "20% off",
                 "description": "Any hot pot set for two people.", "fine_print": "Dine-in only." },
      "zh_CN": { "title": "双人火锅 8 折", "discount_label": "8折" }
    },
    "category_id": 1,
    "city_id": 4,
    "original_price": 69.99,
    "deal_price": 55.99,
    "ends_at": "2026-12-31T23:59:00-05:00",
    "total_quantity": 100,
    "per_user_limit": 1
  }'

To include a cover image, send the same fields as multipart/form-data (e.g. -F "content[en][title]=…" -F "[email protected]"). PNG, JPG or WebP, up to 4 MB.

Webhooks

POST /dealnear/webhook HTTP/1.1
Content-Type: application/json
DealNear-Event: coupon.redeemed
DealNear-Event-Id: evt_01k7jz2q9w3v8x4c5n6m7p8r9t
DealNear-Delivery: 1842
DealNear-Signature: t=1760545869,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_01k7jz2q9w3v8x4c5n6m7p8r9t",
  "type": "coupon.redeemed",
  "created_at": "2026-10-15T12:31:09-04:00",
  "data": {
    "code": "DN-7K4M-Q2XP",
    "status": "redeemed",
    "is_usable": false,
    "deal": { "id": 42, "title": "Hot pot for two, 20% off", "discount_label": "20% off" },
    "customer": { "name": "Jamie" },
    "claimed_at": "2026-10-12T18:04:11-04:00",
    "redeemed_at": "2026-10-15T12:31:09-04:00",
    "expires_at": "2026-11-15T23:59:59-05:00",
    "updated_at": "2026-10-15T12:31:09-04:00"
  }
}

Responding and retries

• Answer with any 2xx status within 10 seconds. Do slow work after you respond, e.g. in a queue.
• Any other status, a timeout or a connection error is retried after 1 minute, 5 minutes, 30 minutes, then 1, 2, 4, 8 and 12 hours — 9 attempts over about 28 hours. Redirects are not followed.
• An event can arrive more than once, and events can arrive out of order. Ignore an id you have already handled, and compare data.updated_at before overwriting newer data.
• If an endpoint fails every attempt for a day, it is disabled and stops receiving events. Fix it, send a test event and enable it again in the merchant center, then catch up with GET /coupons?updated_since=….
• The merchant center shows each endpoint’s recent deliveries and their response status. History is kept for 30 days.

Verifying signatures

PHP

$payload = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_DEALNEAR_SIGNATURE'] ?? ''), $signature);

$expected = hash_hmac('sha256', ($signature['t'] ?? '').'.'.$payload, getenv('DEALNEAR_WEBHOOK_SECRET'));

if (! hash_equals($expected, $signature['v1'] ?? '') || abs(time() - (int) ($signature['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);

Node.js (Express)

import crypto from 'node:crypto';

app.post('/dealnear/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const { t, v1 = '' } = Object.fromEntries((req.get('DealNear-Signature') ?? '').split(',').map((part) => part.split('=')));
  const expected = crypto.createHmac('sha256', process.env.DEALNEAR_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest('hex');

  if (v1.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
      || Math.abs(Date.now() / 1000 - Number(t)) > 300) {
    return res.sendStatus(400);
  }

  const event = JSON.parse(req.body);
  res.sendStatus(204);
});

Errors

Errors are JSON with a human-readable message and, where useful, a stable error code to branch on.

Pagination & limits

• Lists return data, links and meta. Use per_page (up to 100) and follow links.next until it is null.
• To keep your own system in sync, use webhooks, or poll GET /coupons?updated_since=… with the time of your last sync.
• Each key can make 120 requests per minute. Responses include X-RateLimit-Limit and X-RateLimit-Remaining.
• Version 1 only gets backwards-compatible changes (new endpoints and new fields). Ignore fields you do not recognise.

Account

The business behind the API key.

Coupons

Coupons customers have claimed from your deals.

Deals

The offers you publish on DealNear.

Reference

IDs used when creating deals.

Webhook events

Requests DealNear sends to your endpoints when coupons and deals change. Every request has the headers and envelope shown in Webhooks.