{ "info": { "name": "Balaji Customer API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": "Balaji Customer API 1.0.0. Set apiKey to a test key from your Integrations page." }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://shop.balajibrands.com" }, { "key": "apiKey", "value": "" } ], "item": [ { "name": "Catalog", "item": [ { "name": "Look up parts", "request": { "method": "GET", "description": "Look up items by `sku` and/or `upc` (comma lists, 50 identifiers together at most), or search with `q`. You see only the items your account can order, at your own price. Name `sku`/`upc`, or `q`, not both. `cursor` pages a `q` search only.\n\nEach key reads 2,000 item rows a day (Pacific time). Rows returned count; `not_found` entries do not.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/items", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "items" ], "query": [ { "key": "sku", "value": "CL-CASE-IPH16-BK,CL-CASE-IPH16-BL", "disabled": false }, { "key": "upc", "value": "", "disabled": true }, { "key": "q", "value": "", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ], "variable": [] } } }, { "name": "Sync the full catalog", "request": { "method": "GET", "description": "Every item your website account can order, in the `/items` row shape plus `updated_at`, `on_order` and `backorderable`, oldest change first. Pages hold up to 200 rows. A page can hold fewer rows than `limit`, or none, and still have a `next_cursor`: keep paging until it is `null`. On the last page save `next_updated_since` and send it as `updated_since` next time.\n\nYour account can read 50,000 catalog rows a day (Pacific time), shared by all your keys. That is separate from the `/items` allowance.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/catalog", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "catalog" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true } ], "variable": [] } } } ] }, { "name": "Orders", "item": [ { "name": "List orders", "request": { "method": "GET", "description": "Sales orders from every channel (website, phone, your rep, EDI and this API) on your account and its sub-accounts, oldest change first. Changes reach this list up to 15 minutes after they happen.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/orders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "orders" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true }, { "key": "status", "value": "pending_fulfillment,partially_fulfilled", "disabled": false }, { "key": "po_number", "value": "", "disabled": true } ], "variable": [] } } }, { "name": "Place an order", "request": { "method": "POST", "description": "Send one purchase order. It becomes one Balaji sales order on your account terms, placed through the same checkout the website uses, so every check a website order passes applies.\n\n- A **test key** runs every check and returns what the order would be (`\"result\": \"validated\"`). Nothing is placed.\n- **`?dry_run=true`** does the same on any key, including a live key, and saves nothing (`\"result\": \"dry_run\"`). Dry-run a full day's batch before your first live push.\n- A **live key** accepts the order and answers `202` with `\"result\": \"pending_release\"` and `release_after`. The order waits 30 minutes, then goes to the warehouse queue. Cancel it before then with `DELETE /api/v1/orders/{po_number}`. Live keys answer `503 LIVE_ORDERS_PAUSED` until Balaji switches live ordering on for your account.\n\nThe call does not wait for checkout. Read the outcome with `GET /api/v1/orders/{po_number}`: it shows `pending_release`, then the order once it is placed, or `failed` with an `error_code` if checkout refused it (for example `CREDIT_LIMIT_EXCEEDED` or `OUT_OF_STOCK`).\n\nOne PO number places one order. Send the same `po_number` again and nothing new is saved: you get the existing order back, with `\"result\": \"already_placed\"` once it is placed. That makes a retry after a timeout safe.\n\nIf any line has a problem, nothing is accepted and the error lists every bad line.\n\n**Holds.** An order that looks wrong is accepted and held, not refused: it answers `202` with `\"result\": \"held\"` and a `holds` list, and nothing reaches checkout until a person releases it. A hold names the line and the number it was compared with. Holds: `LINE_QUANTITY_ABOVE_HISTORY` (a line over 10 times your largest line in the last 90 days), `ORDER_TOTAL_ABOVE_HISTORY` (a subtotal over 5 times your largest order in the last 90 days) and `CASE_PACK_ROUNDED` (a quantity that is not a whole number of case packs; checkout would round it up, so it is held instead). An item or customer with no 90-day history is not judged. A test key and a dry run show the holds too.\n\n**Daily ceilings.** Each key has a ceiling of orders, units and dollars a day, counted in Pacific time. An order that would pass one answers `429 DAILY_LIMIT_REACHED` and nothing is accepted. A dry run checks the ceiling and reserves nothing.\n", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/orders", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "orders" ], "query": [ { "key": "dry_run", "value": "", "disabled": true } ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"po_number\": \"P26101\",\n \"ship_to\": {\n \"address_id\": 4128\n },\n \"lines\": [\n {\n \"sku\": \"ZZ-TFM-IP17-BK\",\n \"quantity\": 24,\n \"unit_price\": 4.31,\n \"line_ref\": \"1\"\n },\n {\n \"upc\": \"812345678901\",\n \"quantity\": 12\n }\n ],\n \"notes\": \"Deliver to back door\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get an order by your PO number", "request": { "method": "GET", "description": "Status, total and shipments of one order on your account or a sub-account, found by your own PO number. An order this API accepted shows here while it is held or waiting out its release window, before it is a sales order. A new shipment can take up to 15 minutes to appear. Check no more than once every 15 minutes per order; use `GET /api/v1/orders` to follow many orders.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/orders/:po_number", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "orders", ":po_number" ], "query": [], "variable": [ { "key": "po_number", "value": "P26101" } ] } } }, { "name": "Cancel an order", "request": { "method": "DELETE", "description": "Cancels an order this API accepted while it is still held or waiting out its 30-minute release window. After that it has gone to the warehouse queue and cancellation goes through customer service (`CANCEL_WINDOW_CLOSED`). Cancelling twice answers cancelled again. An order checkout refused was never placed (`ORDER_NOT_PLACED`). It gives back the order's daily ceiling slot.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/orders/:po_number", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "orders", ":po_number" ], "query": [], "variable": [ { "key": "po_number", "value": "P26101" } ] } } }, { "name": "Get an order by Balaji order number", "request": { "method": "GET", "description": "One order on your account or a sub-account by its Balaji order number, with its shipments. Use it for orders placed without a PO number.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/orders/by-number/:order_number", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "orders", "by-number", ":order_number" ], "query": [], "variable": [ { "key": "order_number", "value": "SO51696890123" } ] } } } ] }, { "name": "Shipments", "item": [ { "name": "List shipments", "request": { "method": "GET", "description": "Fulfillments on your account and its sub-accounts with order number, PO, ship method, tracking numbers and links, and the last UPS status we recorded. `carrier` and `url` are `null` when the carrier cannot be told from the number. Changes reach this list up to 15 minutes after they happen.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/shipments", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "shipments" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true } ], "variable": [] } } } ] }, { "name": "Finance", "item": [ { "name": "List invoices", "request": { "method": "GET", "description": "Invoices on your account and its sub-accounts, oldest change first. `open=true` keeps invoices with an amount due. Each row links its PDF at `pdf_url`.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "invoices" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true }, { "key": "open", "value": "", "disabled": true } ], "variable": [] } } }, { "name": "Get an invoice", "request": { "method": "GET", "description": "One invoice with its lines. Another account's invoice and a missing one both answer 404.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/invoices/:invoice_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "invoices", ":invoice_id" ], "query": [], "variable": [ { "key": "invoice_id", "value": "8800123" } ] } } }, { "name": "Download an invoice PDF", "request": { "method": "GET", "description": "The invoice as the branded Balaji PDF. Another account's invoice and a missing one both answer 404.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/invoices/:invoice_id/pdf", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "invoices", ":invoice_id", "pdf" ], "query": [], "variable": [ { "key": "invoice_id", "value": "8800123" } ] } } }, { "name": "List credit memos", "request": { "method": "GET", "description": "Credit memos on your account and its sub-accounts, with the invoices each was applied to and what is still unused.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/credit-memos", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "credit-memos" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true } ], "variable": [] } } }, { "name": "List payments", "request": { "method": "GET", "description": "Customer payments on your account and its sub-accounts, with the invoices each was applied to and any amount not yet applied.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/payments", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "payments" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true } ], "variable": [] } } }, { "name": "List returns", "request": { "method": "GET", "description": "Return authorizations (RMAs) on your account and its sub-accounts, with the order each came from and the credit memo it produced, when there is one.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/returns", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "returns" ], "query": [ { "key": "updated_since", "value": "2026-11-05T08:00:00Z", "disabled": false }, { "key": "cursor", "value": "", "disabled": true }, { "key": "limit", "value": "", "disabled": true } ], "variable": [] } } }, { "name": "Get your statement", "request": { "method": "GET", "description": "Your open balance, aging buckets and open items: open invoices, then unused credit memos and payments as negative amounts, so the open items sum to the balance. It is the current state only. There is no `as_of` parameter; the `as_of` field reports how fresh the data is.\n", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/statement", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "statement" ], "query": [], "variable": [] } } } ] }, { "name": "Ship-tos", "item": [ { "name": "List ship-to addresses", "request": { "method": "GET", "description": "Your own ship-to addresses. Map your store codes to `address_id` once with `PUT /api/v1/ship-to-map`.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/ship-tos", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "ship-tos" ], "query": [], "variable": [] } } }, { "name": "Get your store map", "request": { "method": "GET", "description": "Your store codes and the ship-to address each maps to.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/ship-to-map", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "ship-to-map" ], "query": [], "variable": [] } } }, { "name": "Replace your store map", "request": { "method": "PUT", "description": "Replaces your whole store map. Store codes are not case sensitive. If any `address_id` is not one of your addresses, nothing is saved. Once you have a map, every `POST /api/v1/orders` must name `ship_to.store_id` and ships to the address that store maps to.\n", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/ship-to-map", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "ship-to-map" ], "query": [], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"stores\": [\n {\n \"store_id\": \"S17\",\n \"address_id\": 4128\n },\n {\n \"store_id\": \"S18\",\n \"address_id\": 4129\n }\n ]\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Webhooks", "item": [ { "name": "List webhook endpoints", "request": { "method": "GET", "description": "Your account's webhook endpoints, newest first. Sending is switched off until Balaji turns it on for your account; registration works before that.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks" ], "query": [], "variable": [] } } }, { "name": "Add a webhook endpoint", "request": { "method": "POST", "description": "Registers an https endpoint for the events you list. The answer carries the signing secret (`whsec_...`) once; store it, because it is never shown again. A test key makes a test endpoint and a live key a live one. Up to 10 endpoints per account: a further one answers 409 `TOO_MANY_ENDPOINTS`, and a URL that is not https or not public answers 422 `INVALID_URL`.\n\nEach delivery is a POST with the header `Balaji-Signature: t=,v1=`, where `v1` is HMAC-SHA256 of `.` with your secret. Reject a signature older than 5 minutes.\n", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks" ], "query": [], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"url\": \"https://erp.example.com/balaji/hooks\",\n \"events\": [\n \"order.created\",\n \"order.updated\",\n \"shipment.created\"\n ],\n \"description\": \"ERP order sync\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get a webhook endpoint", "request": { "method": "GET", "description": "One endpoint. Another account's endpoint and a missing one both answer 404.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:endpoint_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":endpoint_id" ], "query": [], "variable": [ { "key": "endpoint_id", "value": "cwe_8f2c1a9b0d3e4f56" } ] } } }, { "name": "Change a webhook endpoint", "request": { "method": "PATCH", "description": "Send any of `url`, `events`, `description`, or `enabled true` to turn a disabled endpoint back on. A bad URL answers 422 `INVALID_URL`.", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:endpoint_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":endpoint_id" ], "query": [], "variable": [ { "key": "endpoint_id", "value": "cwe_8f2c1a9b0d3e4f56" } ] }, "body": { "mode": "raw", "raw": "{\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Remove a webhook endpoint", "request": { "method": "DELETE", "description": "Removes the endpoint and drops its unsent events.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:endpoint_id", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":endpoint_id" ], "query": [], "variable": [ { "key": "endpoint_id", "value": "cwe_8f2c1a9b0d3e4f56" } ] } } }, { "name": "Send a test event", "request": { "method": "POST", "description": "Sends one sample event of the type you name, marked `test true`, once, and answers with what your endpoint returned. A failed test never disables the endpoint. 503 `WEBHOOKS_PAUSED` while sending is switched off; 409 `ENDPOINT_DISABLED` for a disabled endpoint.", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:endpoint_id/test", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":endpoint_id", "test" ], "query": [], "variable": [ { "key": "endpoint_id", "value": "cwe_8f2c1a9b0d3e4f56" } ] }, "body": { "mode": "raw", "raw": "{\n \"type\": \"order.created\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "List delivery attempts", "request": { "method": "GET", "description": "Recent attempts for one endpoint, newest first.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:endpoint_id/deliveries", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":endpoint_id", "deliveries" ], "query": [ { "key": "limit", "value": "", "disabled": true } ], "variable": [ { "key": "endpoint_id", "value": "cwe_8f2c1a9b0d3e4f56" } ] } } }, { "name": "Replace the signing secret", "request": { "method": "POST", "description": "Mints a new signing secret and shows it once. The old secret stops working at once.", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/webhooks/:endpoint_id/rotate-secret", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhooks", ":endpoint_id", "rotate-secret" ], "query": [], "variable": [ { "key": "endpoint_id", "value": "cwe_8f2c1a9b0d3e4f56" } ] } } } ] }, { "name": "Partner OAuth", "item": [ { "name": "Exchange a code or refresh a token", "request": { "method": "POST", "description": "For partner platforms only. Authenticate the client with its id and secret (HTTP Basic, or `client_id` and `client_secret` form fields). Grants: `authorization_code` and `refresh_token`. A code or refresh token presented twice revokes its connection. See the partner guide in the docs.\n", "auth": { "type": "noauth" }, "header": [], "url": { "raw": "{{baseUrl}}/api/v1/oauth/token", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "oauth", "token" ], "query": [], "variable": [] }, "body": { "mode": "urlencoded", "urlencoded": [] } } }, { "name": "Revoke a connection", "request": { "method": "POST", "description": "For partner platforms only. RFC 7009 revocation. Either token of a connection revokes the whole connection. It answers 200 for an unknown token, so the call cannot probe for valid tokens.\n", "auth": { "type": "noauth" }, "header": [], "url": { "raw": "{{baseUrl}}/api/v1/oauth/revoke", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "oauth", "revoke" ], "query": [], "variable": [] }, "body": { "mode": "urlencoded", "urlencoded": [] } } } ] } ] }