Developers · API v1.0.0

OpenShop API
one REST /v1 contract.

Shop catalogs, orders, signed webhooks, product feeds and OAuth apps. The contract is an OpenAPI 3.1 file, and this page is its plain-language summary.

Last updated: 2026-11-17 · openshop-v1.yaml ↗

APIREST /v1

Catalog, orders, webhooks, product feeds and OAuth apps, in one OpenAPI 3.1 contract.

Overview

Four ways to connect.

  • API key — one shop
  • OAuth app — many shops
  • Webhook — every event
  • Product feed — no token
Get started

Connect in four steps.

The examples use real hosts and real endpoints. Just replace demo with your shop's name.

  1. 01 / 04

    Get an API key

    In your shop console, create a key under Settings → Integrations → API keys and choose the scopes you need. The key is shown only once; if it leaks, revoke it right there.

    # Keep the key in an environment variable, never in your code
    export OPENSHOP_API_KEY="osk_live_…"
  2. 02 / 04

    Your first request

    The catalog is open without a token: read it directly on the shop's own host. To read orders, put a key with order:read in the Authorization header.

    # Catalog: no token, on the shop's own host
    curl "https://demo.openshop.mn/api/v1/shop/products?limit=5"
    
    # Orders: with a key that has order:read
    curl "https://api.openshop.mn/v1/shop/orders?status=paid&limit=20" \
      -H "Authorization: Bearer $OPENSHOP_API_KEY"
  3. 03 / 04

    Connect a webhook

    In the same Integrations section of the console, register your HTTPS address and choose your events. Check each request's X-OpenShop-Signature header BEFORE parsing the raw body.

    Webhook details →
    import crypto from "node:crypto";
    
    // rawBody = the unparsed Buffer (for example express.raw({ type: "application/json" }))
    export function verifyOpenShop(secret, header, rawBody, nowMs = Date.now()) {
      const parts = header.split(",").map((p) => p.trim().split("="));
      const t = parts.find(([k]) => k === "t")?.[1];
      const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => v);
      if (!t || sigs.length === 0) return false;
      if (Math.abs(Math.floor(nowMs / 1000) - Number(t)) > 300) return false;
    
      const expected = crypto
        .createHmac("sha256", secret)
        .update(t + ".")
        .update(rawBody)
        .digest("hex");
      // During a 24-hour secret rotation the header carries two v1 values; either one is valid.
      return sigs.some(
        (s) =>
          s.length === expected.length &&
          crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)),
      );
    }
  4. 04 / 04

    Build an app (OAuth)

    For an app that serves many shops, register it under app.openshop.mn → Developer. When a merchant installs your app they approve its scopes, and you get a token for each shop.

    How to build an app →
    # 1) Send the merchant to the consent page (PKCE S256 required)
    https://id.openshop.mn/oauth2/authorize?response_type=code
      &client_id=app_…&redirect_uri=https://your.app/callback
      &scope=order:read%20product:read&state=…
      &code_challenge=…&code_challenge_method=S256
    
    # 2) Exchange the returned code for tokens
    curl -X POST https://id.openshop.mn/oauth2/token \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -d grant_type=authorization_code \
      -d code=… -d redirect_uri=https://your.app/callback \
      -d code_verifier=…
Authentication

An API key or an OAuth app.

To connect one shop's own systems, use an API key. For an app installed by many shops, use OAuth: no keys are passed around by hand.

API keyOAuth app
ForOne shop connecting its own POS, ERP or accounting systemAn app installed by many shops
Where to createConsole → Settings → Integrationsapp.openshop.mn → Developer (DAN-verified)
Credentialosk_live_… — shown only onceosa_live_… (1 hour) + osr_live_… refresh token
PermissionsThe scopes chosen for the keyThe scopes the merchant approved
WebhooksRegister endpoints in the consoleCreated automatically for each install
A

Shop API key

Create it under Settings → Integrations in the console. Keys look like osk_live_… and are shown only once.

HTTP
GET https://api.openshop.mn/v1/shop/orders
Authorization: Bearer osk_live_…
  • Host: https://{slug}.openshop.mn/api/v1/shop/* or https://api.openshop.mn/v1/shop/*; the key itself names its shop. On another shop's host you get 401 invalid_api_key.
  • Catalog reads (GET /shop/products*, /shop/categories*) are open without a token; with a product:write key, drafts show too.
  • Idempotency-Key on POST /shop/checkout: the same response for 24 hours, 422 idempotency_key_reuse with a different body.
  • Cost (cost_mnt) is never returned to any key.
B

App (OAuth 2.0 + PKCE)

Accept the developer terms under app.openshop.mn → Developer (you must be DAN-verified) and register your app.

  1. Create the app (≤5): name, logo, https redirect URI (exact match), requested scopes, webhook URL. The client_secret is shown once.
  2. Development mode: test a draft app by installing it only in shops you own.
  3. Submit for review → OpenShop checks it and makes it a test app (in chosen shops) or published (App directory), or returns it with a reason.
  • Tokens: osa_live_… (1 hour) · osr_live_…, a new pair on every use; sending an old one again revokes every token of the install.
  • POST /oauth2/revoke (RFC 7009). As soon as the merchant disconnects the app, the next request gets 401 invalid_token.
  • GET /shop/orders/export is closed to apps; sync with the list plus webhooks.
C

Scopes

A scope = the console permission name, the same closed list for API keys and apps. Permissions to manage staff, roles or keys are never granted to any credential. A missing permission gives 403 insufficient_scope + required_scope.

  • product:read
  • product:write
  • product:delete · sensitive
  • order:read
  • order:write
  • customer:read · sensitive

Without customer:read, the buyer fields on orders are null + pii_redacted: true. An app asking for a sensitive scope justifies it in writing during review.

Webhooks

Signed, delivered at least once.

Register your HTTPS address in the Integrations section of the console and choose your events. The body is a thin envelope without personal data; fetch the details from the API.

01

Request shape

Events
  • order.created
  • order.paid
  • order.expired
  • order.shipped
  • order.fulfilled
  • order.unfulfilled
  • product.created
  • product.updated
  • product.deleted
  • order.underpaid
  • order.charge_created
  • order.charge_paid
  • product.published
  • customer.created
  • customer.updated
  • gift_card.created
  • booking.confirmed
  • booking.balance_paid
  • booking.cancelled
  • booking.expired
  • review.created
  • review.updated
  • payment_link.paid
  • survey.response_created
POST · webhook
POST https://your.app/openshop-webhook
X-OpenShop-Event-Id: <the event id: deduplicate on this>
X-OpenShop-Delivery-Id: <new for every attempt>
X-OpenShop-Event-Type: order.paid
X-OpenShop-Api-Version: 2026-09
X-OpenShop-Signature: t=1750000000,v1=06f35f44…
User-Agent: OpenShop-Webhooks/1.0 (+https://openshop.mn)
{"id":"evt_1","type":"order.paid","occurred_at":"…",
 "created_at":"…","api_version":"2026-09",
 "shop":{"slug":"demo"},
 "data":{"order_id":"…","status":"paid","total_mnt":50000,
         "discount_mnt":0,"paid_at":"…"}}
02

Verifying the signature

v1 = HMAC-SHA256(secret, t + "." + rawBody), hex. Check it before parsing the raw body, and limit t to ±300 seconds. During a 24-hour secret rotation the header carries two v1 values; either one matching is valid. Node.js and Go examples are in Step 3.

Test vector

secret
s3cr3t
body
{"id":"evt_1","type":"order.paid"}
t
1750000000
v1
06f35f44b88eceb2f2df6696c68710a8265597b7ca7d225a71d588159757f0d9
03

Retries and ordering

  • An event can arrive twice → deduplicate on X-OpenShop-Event-Id. Order is not assured: order.paid can arrive after order.expired; the final state is GET /shop/orders/{id}.
  • Return 2xx right away (10-second timeout). 5xx · 408 · 429 · timeout → 1m · 5m · 30m · 2h · 6h · 12h · 24h (±20%), 8 attempts in total ≈ 45 hours. Other 4xx → stops at once; 410 → the endpoint is switched off.
  • Endpoints must be https and public; redirects are not followed.
04

Bulk redelivery

After an outage, use Resend all failed in the console or POST /shop/webhooks/{id}/replay: one new attempt for each failure (same X-OpenShop-Event-Id), ≤100 per request, once a minute per endpoint.

App webhooks: an endpoint filtered by scope is created automatically for every install, with X-OpenShop-Installation-Id · X-OpenShop-Shop headers. On disconnection you get app.uninstalled; delete that shop's data within 30 days.

Product feed

Google Merchant · Meta Commerce Manager.

Every shop has a token-free feed on its own host. Just give its link to your catalog's Scheduled fetch.

01

Addresses and formats

feed
GET https://{slug}.openshop.mn/api/v1/shop/feed.csv
    → text/csv (UTF-8 BOM, RFC 4180)
GET https://{slug}.openshop.mn/api/v1/shop/feed.xml
    → RSS 2.0 + xmlns:g (Google Merchant)

Cached for 5 minutes, ETag → If-None-Match = 304. 30 requests/min per visitor IP.

02

What is included

  • Every active product; drafts never. No cost and no stock counts.
  • A product with one variant = one row, id = the product UUID (the same as Pixel's content_ids). 2+ variants → a row per variant, item_group_id = the product UUID.
  • Price "50000 MNT"; sale_price only while a sale is active and confirmed by the price history: the same calculation as the shop.
Limits and errors

429, Retry-After and {error, code}.

Every bucket is separate, so one integrator cannot block others. Branch on the machine-readable code, not the text.

01

Limits

Rate limit buckets
SurfaceLimitBucket
Read requests with an API key600 / minper key
Write requests with an API key120 / minper key
Reads / writes with an app token600 / 120 minper install
All installs of one app together6000 / minclient_id
POST /oauth2/token (app)60 / minclient_id
POST /shop/checkout (no token)30 / minvisitor IP
GET /shop/feed.csv · feed.xml30 / minvisitor IP
GET /shop/suggest120 / minvisitor IP
POST /shop/orders/lookup10 / minvisitor IP

Keyed requests carry X-RateLimit-Limit / Remaining / Reset headers; above the limit, 429 rate_limited + Retry-After.

02

The error envelope

HTTP 409
HTTP 409
{"error": "Not enough stock.",
 "code": "insufficient_stock", "remaining": 2}

error = text to show people (it can change). code = the contract: new ones are added, existing ones are never renamed. For a code you do not recognise, go by its HTTP status.

Error codes
  • out_of_stock
  • insufficient_stock
  • promotion_not_stackable
  • payments_not_ready
  • pickup_unavailable
  • delivery_unavailable
  • payable_closed
  • payment_pending
  • rate_limited
  • unauthorized
  • invalid_api_key
  • insufficient_scope
  • api_key_scope_invalid
  • api_key_limit_reached
  • webhook_url_invalid
  • webhook_events_invalid
  • webhook_limit_reached
  • not_found
  • validation_error
  • idempotency_key_invalid
  • idempotency_in_progress
  • idempotency_key_reuse
  • endpoint_sunset
  • invalid_signature
  • connector_required
  • connector_not_linked
  • invalid_token
  • app_route_not_allowed
  • webhook_app_managed
  • webhook_endpoint_inactive
  • webhook_replay_in_flight
  • buyer_email_required
  • digital_qty_invalid
  • already_enrolled
  • module_disabled
  • manual_order_invalid
  • min_order_not_met
  • history_not_restorable

Removals = Deprecation + Sunset headers, at least 6 months' notice, then 410 endpoint_sunset. No endpoint is deprecated at the moment.

Changelog

What was added in v1.

Only additive changes ship in v1; a breaking change would be /v2.

  1. 2026-11-17

    New webhook events, signing secret shown once

    • 15 new events: customer.created · customer.updated · gift_card.created · booking.confirmed · booking.balance_paid · booking.cancelled · booking.expired · review.created · review.updated · payment_link.paid · survey.response_created · order.underpaid · order.charge_created · order.charge_paid · product.published.
    • GET /shop/webhooks/events: every event carries group, group_label and since (catalogue version 2026-09 or 2026-11). The payload api_version stays 2026-09 — fields are only ever added.
    • Every new payload carries ids, status, amounts and dates only: never a name, phone, address, email, gift card code or survey answer.
    • The full signing secret is returned once, by create or rotate; endpoints show secret_last4. Rotating needs a recent sign-in (403 reauth_required); the old secret keeps verifying for 24 hours.
  2. 2026-09-24

    Third-party apps (OAuth), customer:read

    • appOAuth: authorization code + PKCE (S256 required), confidential client; a merchant installs it in one shop and approves every scope.
    • Tokens: osa_live_… (1 hour) · osr_live_… (rotating; reusing one revokes every token of the install) · POST /oauth2/revoke (RFC 7009).
    • New scope customer:read for the buyer details on orders; without it they are null + pii_redacted. Added automatically to existing order:read keys and permissions.
    • App webhooks: an endpoint per install filtered by scope, X-OpenShop-Installation-Id · X-OpenShop-Shop, app.uninstalled.
  3. 2026-09-22

    Product feed (CSV · XML)

    • GET /shop/feed.csv, GET /shop/feed.xml in Google Merchant / Meta Commerce Manager format, no token.
    • A 5-minute cache per shop and format, ETag / If-None-Match → 304, 30 requests/min.
  4. 2026-09-16

    API keys, webhooks, Idempotency-Key, a machine-readable contract

    • Authorization: Bearer osk_live_… — a key per shop, scope = permission slug (product:read/write/delete, order:read/write).
    • Outgoing webhooks: order.* · product.* events, X-OpenShop-Signature (HMAC-SHA256), 8 attempts ≈ 45 hours.
    • Idempotency-Key on POST /shop/checkout (24-hour replay, 409 while in progress, 422 with a different body).
    • Deprecation / Sunset policy (RFC 9745 / 8594, ≥6 months); the OpenAPI 3.1 contract is checked in CI with spectral + oasdiff.
  5. 2026-09-08

    Public shop API — 5 fixes

    • Public responses no longer include cost_mnt.
    • Rate-limit buckets per visitor (instead of one shared bucket).
    • GET /shop/checkout/{id} returns paid_at once paid.
    • CORS: only origins named in PUBLIC_API_CORS_ORIGINS, and only on read routes.
    • A machine-readable code in the error envelope (out_of_stock · insufficient_stock + remaining …).