POD API onboarding guide

Get access

1. Create a Shrutgyan customer account and give our team the registered email address.
2. Ask our team to enable POD client access and approve the exact hostnames where you store print-ready PDFs.
3. Arrange prepaid credit. Our team adds it manually; your account cannot add its own balance.
4. Open My account → Print on demand. Generate a named API key and copy it immediately. Confirm your login password when generating a key.
5. Get your integration address privately from our team and save it as POD_API_URL on your server.

Keys expire after 90 days by default; choose 1–365 days. Up to five keys can be active per account. A full key is shown only once. If you lose it, revoke it and generate another.

Authenticate every request

X-POD-Key: YOUR_SECRET_API_KEY
Accept: application/json

Use HTTPS and call the API from your backend. Store the key in a secret manager or environment variable. Keep it out of frontend JavaScript, mobile app bundles, source control, URLs, screenshots, and application logs.

Do not use WordPress application passwords or the Authorization header for this API. Browser-origin requests and URL query parameters are rejected. Access is limited to your own prepaid account and jobs.

Rotate a key by creating and deploying a replacement, then revoking the old key. Disabling a client account revokes all its keys; re-enabling it requires new keys.

Follow this integration flow

1. Read GET /options for valid print settings and Indian state codes, and GET /account for your balance and approved file hostnames.
2. Send an items array of book print settings to POST /quote to calculate each book and the complete printing total.
3. Prepare the order with an items array containing every book and its final PDF URLs, one shipping_address, a unique external_reference, and max_total_minor set to your approved printing total.
4. Persist a new Idempotency-Key with the complete order JSON before submitting it.
5. Send POST /jobs. Save the returned job_id, which identifies the whole recipient order. All book entries and one combined printing debit are committed together.
6. Use GET /jobs/{job_id} to read the order, each book’s production status, and the receipt state.

Quoting does not reserve funds or lock a price. Submission recalculates the price on the server. If the total exceeds your maximum, or your balance is insufficient, no job or debit is created.

API resources

Append these relative paths to the privately supplied POD_API_URL, without a trailing slash.

Print settings for each book

Each object in items requires all eight fields below. Different books can use different print settings and quantities. Codes are strings; pages and qty are JSON integers. Query /options for the current accepted codes.

For colour printing (4C), select ML100, SM100, or SM130. The API rejects ML80 and ML90 for colour jobs.

Submit a job

Send Content-Type: application/json and an Idempotency-Key of 16–128 letters, numbers, underscores, or hyphens. A UUID is suitable. The JSON body limit is 64 KiB. Unknown fields are rejected.

Order fields

Additional fields inside each book

Delivery address fields

Supply these inside shipping_address. Address and contact fields must be single-line strings; unknown fields are rejected.

Files are kept in the supplied order. The submission API records file references; it does not download, inspect, or prove that a URL contains a valid PDF. Provide file links that remain accessible for at least 48 hours after submission. Use your approved storage directly, without redirectors or URL shorteners.

Each book starts as Paid for printing. Shipping charges are still to be settled separately before dispatch. Clients cannot set the charge, account owner, payment state, printer order ID, or production status.

Request examples

The following shell examples read credentials and the private address from environment variables. Replace the illustrative PDF host with an approved hostname for your account.

Check your balance

curl --fail-with-body --silent --show-error \
  -H "X-POD-Key: $POD_API_KEY" \
  -H "Accept: application/json" \
  "$POD_API_URL/account"

Get a quote

Send each book’s settings and number of copies in items. This request is free and does not deduct your balance. Use the combined top-level total_minor as max_total_minor when submitting the whole order. Shipping is not included.

curl --fail-with-body --silent --show-error \
  -H "X-POD-Key: $POD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"items":[
    {"line_reference":"book-1","title":"First book",
     "size":"5585","paper":"ML80","print":"BW",
     "cover_print":"1","cover_lam":"Matt","binding":"PUR",
     "pages":120,"qty":1},
    {"line_reference":"book-2","title":"Second book",
     "size":"5585","paper":"ML80","print":"BW",
     "cover_print":"1","cover_lam":"Matt","binding":"PUR",
     "pages":200,"qty":2}]}' \
  "$POD_API_URL/quote"

Prepare your job JSON

Save the following as job.json. The example maximum is illustrative; use the total from your actual quote.

{
  "external_reference": "YOUR-ORDER-0001",
  "shipping_address": {
    "name": "RECIPIENT NAME",
    "address_1": "HOUSE AND STREET",
    "address_2": "LOCALITY OR LANDMARK",
    "city": "Mumbai",
    "state": "MH",
    "postcode": "400004",
    "country": "IN",
    "phone": "+919876543210"
  },
  "items": [
    {
      "line_reference": "book-1",
      "title": "First book",
      "size": "5585", "paper": "ML80", "print": "BW",
      "cover_print": "1", "cover_lam": "Matt", "binding": "PUR",
      "pages": 120, "qty": 1,
      "book_urls": ["https://files.example.com/first-book.pdf"]
    },
    {
      "line_reference": "book-2",
      "title": "Second book",
      "size": "5585", "paper": "ML80", "print": "BW",
      "cover_print": "1", "cover_lam": "Matt", "binding": "PUR",
      "pages": 200, "qty": 2,
      "book_urls": ["https://files.example.com/second-book.pdf"]
    }
  ],
  "max_total_minor": 100000,
  "dispatch": "Pack all three copies together for this recipient."
}

Submit once

POD_IDEMPOTENCY_KEY is an environment variable containing a unique submission identifier that you generate and save for this job, such as a UUID. It is sent in the Idempotency-Key header so that a retry after a timeout cannot create a second job or charge. Use a new value for each new job; reuse the same value and unchanged job JSON when retrying that job. It is separate from your secret API key.

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  -H "X-POD-Key: $POD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $POD_IDEMPOTENCY_KEY" \
  --data-binary @job.json \
  "$POD_API_URL/jobs"

Understand the response

A newly accepted job returns HTTP 201 with replayed: false. If you retry an already accepted submission, the API returns HTTP 200 with replayed: true and the same job ID. This means your earlier submission succeeded; no additional job or charge was created. Both responses contain:

Retries and errors

Persist both your order reference and idempotency key before the first submission. If a timeout leaves the outcome unknown, retry the same JSON with the same identifiers. A replay does not create a second job or debit. A reference is unique per account even if a different idempotency key is sent.

Reusing either identifier with different job details returns 409 pod_idempotency_conflict. Do not silently change the files, quantity, title, or maximum price on a retry. Contact our team to resolve an accepted job before submitting a replacement.

{"code":"pod_insufficient_balance",
 "message":"Insufficient prepaid balance. Ask Shrutgyan to add credit.",
 "data":{"status":402}}

Balances and submission receipts

The API uses the current Shrutgyan POD calculator for each book. All books, the recipient address, and one combined printing debit are stored together. If any book is invalid or the balance cannot cover the whole order, no book or debit is created. All keys for your account share one balance.

Shipping charges are confirmed and settled separately with our team before dispatch. The prepaid balance deduction and maximum-charge field cover printing only.

Once accepted, one receipt is sent to the client’s registered account email address. It lists every book, quantities, the combined printing charge, and the balance after submission. The delivery recipient is not automatically emailed. No API key, file URL, phone number, or full street address is included in the receipt. Submission acceptance does not confirm printing or dispatch.

If email fails, the job remains accepted and charged. Check notification_status or your account’s submission list; do not create another job to trigger an email. Our team can retry the receipt. Email delivery and spam filtering depend on your mail provider.

View recent submissions and balance transactions in My account → Print on demand. For cancellation or a billing correction, contact our team with the job ID. Cancellation and production edits do not automatically refund or reprice an accepted API job.