Connect your custom-coded website to Booksmor

Have a custom-coded e-commerce site (not Shopify or WooCommerce)? You can still send every order, edit, and refund into your Booksmor books — your developer adds a small piece of code that POSTs a signed payload to Booksmor each time something happens.

Time to set up: ~5 minutes for the business owner, ~15–60 minutes for a developer (depending on stack). You’ll need: a developer (or access to your site’s order-creation code).

What you get when this is done

• Every new order on your site → posted as a Sales voucher in Booksmor (with GST split correctly based on the buyer’s state).
• Every refund issued → automatically becomes a Credit Note in Booksmor, linked to the original sale.
• Order edits (price/qty change after creation) → posted as a Debit Note (for increases) or Credit Note (for decreases) for the financial difference. Original sales voucher stays intact for audit.
• Live activity log in Booksmor showing every event received from your site, with delivery status.

Part 1 — Owner: set up the connection in Booksmor (5 minutes)

1. Sign in to your Booksmor account: https://app.booksmor.com.
2. From the left sidebar, click E-Commerce.
3. Click + Connect store (top right).
4. In the dialog:
   • Platform: select Custom-coded site.
   • Display name: anything — e.g. “My main store” or “acme-shop.com”.
5. Click Save.
6. Click the connection name to open its detail page.

On that page you’ll see:

• A Webhook URL card with two read-only fields (Delivery URL + Signing secret). These are what your developer needs.
• A Sample code card with ready-to-paste Python/PHP/Node examples.
• A Download an SDK card with one-click .zip downloads.
• A Verify setup card with a button to fire a test event.
• A Payload schema card with the complete developer reference.

Send the connection detail page link to your developer — or just send them the Delivery URL + Signing secret if they prefer.

Security note: the signing secret is what authenticates your site’s requests to Booksmor. Treat it like a password — share via a secure channel (your password manager, not email/Slack in plain text).

Part 2 — Developer: integrate (15–60 minutes)

Three paths, pick whichever fits your stack:

Path A — Use the Booksmor SDK (recommended)

The SDK wraps HMAC signing + event headers + response handling into a 3-line API. No external dependencies.

Python:

1. From the connection detail page, click ↓ Python (.zip) in the Download an SDK card.
2. Unzip into your project (or pip install ./booksmor-sdk if you prefer pip).
3. Use it:

from booksmor_sdk import BooksmorClient

bk = BooksmorClient(
    webhook_url="<Delivery URL from Booksmor>",
    webhook_secret="<Signing secret from Booksmor>",
)

# When an order is placed on your site:
bk.send_order(
    external_id="ORD-12345",         # YOUR order id (anything unique)
    customer_name="Asha Rao",
    order_date="2026-05-25",
    buyer_state_code="29",           # 2-digit GST state code; optional
    lines=[
        {"sku": "WIDGET-1", "description": "Widget",
         "quantity": 2, "rate": 100, "tax_rate": 18},
    ],
)

# When the order is edited later (Booksmor posts a DN/CN for the delta):
bk.send_update(external_id="ORD-12345", lines=[...new totals...])

# When you refund part or all of an order:
bk.send_refund(
    external_id="ORD-12345",
    refund_id="REF-9991",
    refund_date="2026-05-25",
    lines=[{"sku": "WIDGET-1", "quantity": 1, "rate": 100}],
)

PHP / Node: same API, same field names. Download the corresponding .zip and read its README.

Path B — Copy the inline snippet

Same code the SDK wraps, just inlined. On the connection detail page, the Sample code card has a tab switcher (Python / PHP / Node) — copy whichever language fits, replace the URL and SECRET constants, drop into your order-creation flow.

Best if you don’t want any third-party files in your codebase.

Path C — Roll your own

If you’re integrating from a stack we don’t have an SDK for (Go, Rust, Ruby, …), the contract is:

Request:

• Method: POST
• URL: the Delivery URL from your connection page (e.g. https://app.booksmor.com/api/v1/ecommerce/webhooks/custom/{tenant_id}/{conn_id})
• Body: JSON, see schemas below
• Headers:
  • Content-Type: application/json
  • X-Booksmor-Event: order.created (or order.updated / order.refunded)
  • X-Booksmor-Signature: <hex> — HMAC-SHA256 of the raw request body, hex-encoded, using your connection’s signing secret as the key

Body shapes:

order.created and order.updated:

{
  "external_id": "ORD-12345",
  "customer_name": "Asha Rao",
  "order_date": "2026-05-25",
  "buyer_state_code": "29",
  "lines": [
    {"sku": "WIDGET-1", "description": "Widget",
     "quantity": 2, "rate": 100, "tax_rate": 18}
  ]
}

order.refunded:

{
  "external_id": "ORD-12345",
  "refund_id": "REF-9991",
  "refund_date": "2026-05-25",
  "lines": [
    {"sku": "WIDGET-1", "description": "Widget",
     "quantity": 1, "rate": 100}
  ]
}

For the full field reference (which fields are required, defaults, type coercion), expand the Payload schema card on the connection page. It has detail tables for every event, every header, and every response code your code might encounter.

Part 3 — Owner & Developer: verify it works

1. On the connection detail page in Booksmor, scroll to the Verify setup card.
2. Pick order.created in the dropdown.
3. Click Send test event.

Booksmor will fire a synthetic, fully-signed test payload at the same webhook URL your developer’s code POSTs to — exercising the exact same path a real order would take.

You should see:

• A green pill: 200 in {milliseconds}ms next to the button.
• A line in Recent activity from your store: “New order #BFW-TEST-xxxxxxxxx — Saved ✓”.
• A test sales voucher in Transactions (reference number starts with BFW-TEST-).

If you see a red pill instead, hover over it for the error. The most common ones are listed in Troubleshooting below.

Now test the real flow: place a real order on your site → it should appear in Booksmor within seconds.

Response codes — what your developer’s code should do

Common questions

What if my site can’t reach Booksmor for a few minutes? Queue the events and retry. Booksmor is idempotent on (connection_id, external_id), so re-sending the same order any number of times is safe (it’ll return 409 after the first success).

How do SKUs match to my Booksmor products? On the connection detail page, the SKU mapping section lets you map each external SKU (whatever your site uses) to a Booksmor item. Unmapped SKUs still import — the line shows as “Unmapped SKU XYZ” on the voucher, and the SKU shows up in your “Unmapped” filter so you can fix mappings progressively without losing orders.

What data does Booksmor receive? Only what you choose to send: order id, customer name (used as a pseudo-customer label), order date, buyer state code (for GST), and line items (SKU, description, quantity, rate, tax rate). Booksmor doesn’t ask for buyer email, address details, or payment information.

Can I integrate multiple sites? Yes — create one Custom-site connection per site in Booksmor. Each has its own Delivery URL + signing secret. Your developer wires each site’s code to the corresponding pair.

Can I rotate the signing secret if it leaks? Yes. In Booksmor: delete the connection and create a new one (new URL + new secret). Update your site’s code with the new pair, deploy, done. Old events would be rejected with 401 — but those wouldn’t have arrived anyway since the URL changed too.

Do I need to handle refunds? Only if your site issues refunds programmatically. If you handle refunds manually in your back office, you can skip the order.refunded event entirely and continue creating credit notes by hand in Booksmor.

What about order updates / amendments? Optional. Send order.updated whenever an order’s line items or amounts change after creation; Booksmor posts a debit-note or credit-note for the difference. If your site never edits orders post-creation, you don’t need this event.

Troubleshooting

Send test event shows a red pill saying “invalid signature” Your stored credentials in the developer’s code don’t match Booksmor’s. Re-copy the signing secret from the Webhook URL card on the connection detail page; make sure you’re signing the raw request body bytes (not the parsed JSON or a re-serialized string).

Real orders fire but nothing shows in Booksmor

1. Open the connection detail page → Recent activity from your store table.
2. If you see Failed entries, hover for the error.
3. If you see nothing at all when an order fires: the site’s code isn’t actually making the POST. Check your site’s logs.

HTTP 401 in production but Send test event works The test event uses Booksmor’s own signing (no developer code involved). 401 in production means your code’s signing is wrong — most often: signing the JSON.stringify’d body twice, or signing the parsed body object instead of the raw bytes.

HTTP 409 keeps appearing That’s idempotency working as designed: your site sent the same external_id twice. Safe to ignore; nothing is duplicated in your books.

Need help? Contact support@booksmor.com with: your connection name in Booksmor, a sample request body + headers from your site’s code, and a screenshot of the Recent activity panel.