Phoneo Partner API

What this API is

Phoneo gives your storefront a live, read-only feed of the inventory belonging to the shops Phoneo has assigned to you. If you run an online store at, say, yourstore.in, this is how yourstore.in lists Phoneo stock: your server pulls the catalog, stores it on your side, and renders it.

A shop is only ever assigned to you after its owner has agreed to share their stock with you. To get access, see Getting set up.

Authentication

Send your key on every request:

curl "https://super.phoneo.in/api/partner/v1/ping" \
  -H "X-Partner-Key: phn_live_a1b2c3d4e5f6g7h8_XXXXXXXXXXXX" \
  -H "Accept: application/json"

Errors

The errors in the table with an error code come back as {"success": false, "error": "…", "message": "…"}. Branch on error, never on message — the message is plain English for your logs and its wording may change. Two responses have a different shape:

• 422 — {"message": "…", "errors": {"limit": ["…"]}}, one entry per failing parameter.
• 429 — {"message": "Too Many Attempts."} with a Retry-After header in seconds.

The three 403 permission errors are deliberately kept apart, because the fix is different for each — and none of them is something you can fix on your side. Quote the exact error string to support@phoneo.in: ability_not_registered and ability_disabled are settings on Phoneo's end, ability_missing means your key needs that permission added.

Key rotation

When Phoneo rotates your key, the new one reaches you the same way the first one did — a one-time link by email (see Getting set up). Your current key keeps working until you open that link, and for 48 hours after. Deploy the new key inside that window and your site never goes down. Build for this: read the key from config, not from a constant in code.

The three kinds of stock

Phoneo sells three different things, and they behave differently. Your catalog will contain all three mixed together, distinguished by source_type:

An item appears only when the shop has marked it visible to everyone and it is for sale. Many shops leave that switched off for new phones and accessories, so expect most of your catalog to be used_phones. Code for all three anyway — a shop can switch them on at any time.

Product key

These live in three separate tables, so a plain numeric id is not unique. Every item is identified by a composite key:

used_phones:1042
new_phone_units:88
other_item_units:310

Store this key on your side. It is what you pass to /products/{key} and to the availability check, and it never changes for the life of the item.

Endpoints

{
  "success": true,
  "message": "pong",
  "partner": {
    "name": "Your Store",
    "key_id": "a1b2c3d4e5f6g7h8",
    "abilities": ["catalog.*"],
    "rate_limit_per_min": 120
  },
  "shops_available": 2,
  "time": "2026-08-29T12:00:00+05:30"
}

{
  "success": true,
  "data": [
    { "handle": "mobile-point", "name": "Mobile Point", "is_online": true }
  ]
}

{
  "success": true,
  "data": [
    {
      "key": "used_phones:1042",
      "source_type": "used_phones",
      "status": "active",

      "shop": { "handle": "mobile-point", "name": "Mobile Point", "is_online": true },

      "title": "Apple iPhone 13 128GB Blue",
      "slug": "apple-iphone-13-128gb-blue",
      "brand": "Apple",
      "model": "iPhone 13",
      "variant": "128GB",
      "color": "Blue",
      "condition": "Good",
      "description": "Single owner, no scratches",

      "sale_price": "45999.00",
      "price_hidden": false,
      "currency": "INR",
      "stock_quantity": 1,

      "main_category_id": 3,
      "main_category": {
        "id": 3,
        "name": "Mobiles",
        "thumb": "https://img.phoneo.in/Phoneo/2025/Image/Enjoyer/E5/MainCat/MainCat-3/Thumb/b.jpg"
      },

      "thumb": "https://img.phoneo.in/2026/Image/E5/UsedPhone/UP-1042/Thumb/a.jpg",
      "images": ["https://img.phoneo.in/…", "https://img.phoneo.in/…"],
      "attributes": {
        "battery_health": "89%",
        "bill_box_cable_warranty": "Box only",
        "offer": "Festive"
      },

      "updated_at": "2026-08-29T11:42:10+05:30"
    }
  ],
  "paging": { "limit": 100, "next_cursor": 1042, "has_more": true }
}

GET /products?updated_since=2026-08-29T06:00:00%2B05:30

GET /products/availability?keys=used_phones:1042,other_item_units:310

{
  "success": true,
  "data": [
    { "key": "used_phones:1042", "status": "active", "available": true,
      "sale_price": "45999.00", "price_hidden": false,
      "updated_at": "2026-08-29T11:42:10+05:30" },

    { "key": "other_item_units:310", "status": "removed", "available": false,
      "sale_price": "1499.00", "price_hidden": false,
      "updated_at": "2026-08-29T10:10:00+05:30" }
  ]
}

Pricing & the hidden-price rule

if (product.price_hidden) {
  showEnquiryButton();            // "Price on request"
} else {
  showPrice(parseFloat(product.sale_price));
}

Categories

Each shop groups its stock into categories of its own (for example "Mobiles", "Accessories"). A product carries its category twice: as the raw id main_category_id for your own joins, and as a ready-made main_category object with the name and image filled in, so you do not need a second lookup just to render a breadcrumb.

GET /categories returns every category you can currently see:

{
  "success": true,
  "data": [
    {
      "id": 3,
      "name": "Mobiles",
      "thumb": "https://img.phoneo.in/Phoneo/2025/Image/Enjoyer/E5/MainCat/MainCat-3/Thumb/b.jpg",
      "sub": []
    },
    {
      "id": 7,
      "name": "Accessories",
      "thumb": null,
      "sub": []
    }
  ]
}

Only categories that actually contain a product you can see are listed, so this list shrinks and grows with the catalog. sub is always an empty array — Phoneo no longer has sub-categories (see the Changelog). The key is kept so that code written against the earlier nested shape keeps working.

How to keep your site in sync

1. Once, at setup: walk GET /products with the cursor until has_more is false. Store every item's key and updated_at.
2. Every 5–15 minutes: call GET /products?updated_since=<the newest updated_at you hold>. Upsert rows with status: "active"; remove rows with status: "removed".
3. At checkout, every time: GET /products/availability for the items in the basket.
4. Once a day: re-walk the full catalog and reconcile against your copy. This is the safety net that catches anything the delta missed.

What you will never receive

These fields are deliberately excluded, and no parameter will turn them on:

• IMEI and serial numbers (IMEI, SN, WSN)
• Purchase price, sold price, or any margin figure
• Supplier, vendor or customer details of any kind
• Private/internal notes and tags
• HSN/SAC and other tax fields
• The shop's numeric id, phone number or address

If your integration genuinely needs something in this list, raise it with Phoneo as a scope question. It is not a setting anyone can flip on the API.

Getting set up

1. Request access. Email support@phoneo.in with your company name, your website, the email address the key should go to, the Phoneo shops whose stock you want to list, and — if you have them — your servers' fixed outbound IPs.
2. Shop consent. Phoneo confirms with each shop owner before assigning their shop to you. You only ever see shops that have agreed.
3. Receive your key. Phoneo emails you a one-time link. Open it and press Reveal my API key. The key is created at that moment and shown once — copy it straight into your server's configuration. It cannot be looked up again, only replaced.
   • The link expires after 24 hours and works only once.
   • If the link says it has already been used and you did not open it, email support@phoneo.in straight away — someone else may have opened it. Phoneo will switch that key off and send you a new link.
   • If it has expired, ask for a new one. Each new link cancels the previous one.
4. Confirm the connection with GET /ping.
5. Do the full catalog walk, then put the 5–15 minute delta job on a schedule.

A Postman collection and environment file are available alongside this document. Questions: support@phoneo.in.

Changelog