Orbit listing generation

Orbit turns what a seller says and the photos they take into a finished listing, written into your own listing fields (the facts a listing in your shop carries, such as storage, colour or mileage, set up on the Set up your listing fields page).

What a listing means, and what it does not

• It is a draft for the seller to check. Show it to the seller and let them change it before it goes live.
• Orbit is not a fraud check. It describes what the seller says and what the photos show. It cannot tell a real item from a fake, and it never calls an item genuine unless the seller does, and then only as the seller's words. Do not use it to decide whether an item is real.
• Orbit reads photos to help describe the item. It does not promise to notice everything in them. When photos and notes show different items, Orbit asks the seller first. If the answer does not resolve it, the run fails with ORBIT_PHOTOS_DONT_MATCH.
• Every value says where it came from (pcific.sources), so you can show the seller's own words and the web pages used.
• complete: false means the seller was asked for a required field and could not say. The business must fill it in before publishing.
• Orbit never converts a price from one currency to another. A price is the seller's own, or an estimate based on real prices from at least two different web pages. With fewer sources, Orbit returns no price rather than inventing one.

How you can use it

Before you start

• An API key (a secret password your server sends with each request) with the orbit permission. Photos need orbit or safeguard. Reading and changing Orbit's settings needs a test key with the settings permission. See API keys and permissions.
• Orbit switched on. It is on by default. Switched off, every call that starts work is refused with 403 ORBIT_TURNED_OFF.
• Published listing fields. Orbit writes only into fields you define, and refuses with 409 ORBIT_NO_SCHEMA until you publish them.
• Your currency. It is GBP unless you change it with the currency setting. Every price field in your listing fields must allow it (422 CURRENCY_NOT_IN_SCHEMA otherwise).
• Optional: the pricing setting, if you want the price check, and Safeguard switched on, if you want the review or the buyer FAQ. The settings are on the Shop configuration page.
• Your server makes the calls, never the seller's browser, so the key stays secret.

How it works

Orbit works in the background, so no call waits for the AI. Starting a listing answers at once with its runId (the listing's id, your ticket). You read the listing back with that id. A listing is kept for 30 minutes after its last change.

• Category. Orbit uses the category you send. Otherwise it searches your categories by plain words, using each category's description and keywords. If the item is not something you sell, it asks the seller what they meant to list, and if they insist it fails with ORBIT_NO_CATEGORY.
• Questions. If the request is too vague to fill the required fields, Orbit asks everything at once, before it researches. A field you mark x-pcific-ask-seller in your listing fields is always asked of the seller, never guessed.
• Verification. Orbit searches to verify checkable brand, model, storage, official specifications and release year. It never searches for condition, the seller's own description, asking price or generic care advice. It skips search when nothing checkable is present, such as a complete plain unbranded shirt. If a source disagrees, Orbit asks the seller with the source URL and keeps their information until they answer. The model decides using these instructions, with at most 4 searches.
• Checking. Your listing fields decide what is right. Orbit adds no rules of its own. A value that does not fit them is sent back to be fixed, and after 6 refused tries the listing fails with ORBIT_UNFINISHED.
• Your listing style. The listingStyle setting says how titles and descriptions are written. The about setting tells Orbit what you sell.

Quickstart

Use a test key (it spends no credits). The examples set it as $PCIFIC_TEST_KEY. Each step shows the real reply.

Step 1: upload the photos

If a photo decoder stops unexpectedly, a successful upload can contain accepted images plus problems naming each failed photo, its original position and what to try next. Keep the returned image ids and upload only the failed photos again. If ordinary photo validation refuses the request with 422, none of that request's photos are saved; fix the listed problems and send all photos again.

PCIFIC cleans each uploaded fileName before storing or returning it: folder names, control characters and .. are removed. If nothing remains, it uses upload.jpg, upload.png or upload.webp according to the Content-Type.

Send the photos as a multipart form (a form that carries files). Use JPEG, PNG or WebP, up to 12 photos, 15 MB each and 60 MB in all. iPhone HEIC photos are refused: see iPhone photos (HEIC) below.

curl -X POST https://business.pcific.ai/api/v1/images \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -F "photo=@front.jpg" \
  -F "photo=@back.jpg"

{
  "images": [
    {
      "id": "3f1c2a9e-5b7d-4e21-9c0a-6d8f4b1e7a52",
      "width": 4032,
      "height": 3024,
      "preview": "https://photos.pcific.example/preview.webp?signature=...",
      "listing": {
        "url": "https://photos.pcific.example/listing.webp?signature=...",
        "format": "webp"
      },
      "expiresAt": "2026-10-15T10:30:00Z",
      "fileName": "front.jpg"
    }
  ]
}

The preview and listing links are signed links that stop working at expiresAt. Photos are kept for 30 minutes after upload and for 30 minutes after the listing that uses them finishes. Save the copy you want to keep.

iPhone photos (HEIC)

PCIFIC accepts JPEG, PNG and WebP only. iPhones save photos as HEIC, and PCIFIC does not convert HEIC on its servers: decoding it takes a lot of memory and is expensive, so a HEIC photo is refused with PHOTOS_REFUSED.

• Keep the photo picker's accept list to image/jpeg, image/png and image/webp. iPhone Safari, and every browser on iPhone (they all use Safari's engine), usually converts photos picked from the Photos library to JPEG by itself.
• That is not guaranteed. Photos picked through Browse or the Files app often arrive as HEIC, and the behaviour has varied between iOS versions. As a safety net, convert the photo in the seller's browser before you upload it, with the snippet below.
• If the conversion fails (desktop Chrome, for example, cannot read HEIC), show the seller a clear message asking them to save the photo as JPEG and try again.

// Turns a picked photo, HEIC included, into a JPEG of at most 2,500 pixels on its longest side.
// Resolves to null when this browser cannot read the file.
function toJpeg(file) {
  return new Promise((resolve) => {
    const url = URL.createObjectURL(file);
    const image = new Image();
    image.onload = () => {
      const scale = Math.min(1, 2500 / Math.max(image.naturalWidth, image.naturalHeight));
      const canvas = document.createElement("canvas");
      canvas.width = Math.round(image.naturalWidth * scale);
      canvas.height = Math.round(image.naturalHeight * scale);
      canvas.getContext("2d").drawImage(image, 0, 0, canvas.width, canvas.height);
      URL.revokeObjectURL(url);
      canvas.toBlob((blob) => resolve(blob), "image/jpeg", 0.9);
    };
    image.onerror = () => {
      URL.revokeObjectURL(url);
      resolve(null);
    };
    image.src = url;
  });
}

Step 2: start the listing

These responses illustrate the Phones schema published in the listing-fields guide. Use the image ids returned by your upload in images, then use your returned runId in every read and follow-up call. Your ids, timestamps, wording and questions will differ.

curl -X POST https://business.pcific.ai/api/v1/listings \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes":"iPhone 13, good condition, works fine. Selling my old phone. No box. Collection preferred. Asking £315.","details":{"price":{"amount":31500,"currency":"GBP"}},"images":["3f1c2a9e-5b7d-4e21-9c0a-6d8f4b1e7a52"]}'

{
  "status": "working",
  "processing": true,
  "deadlineAt": "2026-10-15T10:01:00Z",
  "parts": {
    "listing": "pending",
    "price": "off",
    "safeguard": "off",
    "faq": "off"
  },
  "publishReady": false,
  "runId": "8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75",
  "tryThis": "Read where it is with GET /api/v1/listings/8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75 in a few seconds.",
  "warnings": []
}

Keys that are not Orbit fields are ignored and named in warnings. This call takes an Idempotency-Key header, so a request you send again after a dropped connection starts only one listing (see Errors, limits and retries).

Step 3: show the draft and poll while processing

curl https://business.pcific.ai/api/v1/listings/8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75 \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"

{
  "status": "working",
  "runId": "8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75",
  "processing": true,
  "deadlineAt": "2026-10-15T10:01:00Z",
  "parts": {
    "listing": "pending",
    "price": "off",
    "safeguard": "off",
    "faq": "off"
  },
  "publishReady": false,
  "tryThis": "Read this again in a few seconds."
}

Read every second while processing is true. The draft returns as soon as it is written, with status listing even while optional checks continue. Every response includes parts.listing (pending, ready or failed), parts.price (off, pending, ready or failed), parts.safeguard (off, pending, passed, flagged or failed), parts.faq (off, pending, ready or failed), deadlineAt and publishReady. When Safeguard is on, show and edit the draft but wait to publish until parts.safeguard is passed and publishReady is true. Fill required fields in pcific.unfilled too. Queue wait, drafting, checks and worker recovery share one 3-minute total processing ceiling. A 30-second idle timer resets on each AI answer or completed step; a stuck run stops with ORBIT_TIMED_OUT. Human answer time is excluded from the total ceiling. Answers resume the remaining budget, and retries keep the same ceiling. Near the ceiling Orbit finishes with known facts and lists missing fields in pcific.unfilled, with pcific.complete false. Failed work is not charged. A listing can be read for 30 minutes after its last change; after that GET answers 404 NOT_FOUND.

Step 4: answer the questions, if Orbit asks

If Orbit needs the storage or condition confirmed, the reply to the same call can be:

{
  "status": "questions",
  "processing": false,
  "deadlineAt": null,
  "parts": {
    "listing": "pending",
    "price": "off",
    "safeguard": "off",
    "faq": "off"
  },
  "publishReady": false,
  "runId": "8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75",
  "expiresAt": "2026-10-15T10:30:00Z",
  "questions": [
    {
      "id": "q1",
      "question": "How much storage does it have?",
      "field": "/storage_gb",
      "options": [
        "64",
        "128",
        "256",
        "512",
        "1024"
      ]
    },
    {
      "id": "q2",
      "question": "What condition is it in?",
      "field": "/condition",
      "options": [
        "New",
        "Like new",
        "Good",
        "Fair",
        "For parts"
      ]
    }
  ],
  "warnings": []
}

curl -X POST https://business.pcific.ai/api/v1/listings/8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75/answers \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"answers":[{"id":"q1","answer":"128"},{"id":"q2","answer":"Good"}]}'

That answers 202 with the same body as step 2. Go back to step 3.

Step 5: read the finished listing

{
  "status": "listing",
  "processing": true,
  "deadlineAt": "2026-10-15T10:01:00Z",
  "parts": {
    "listing": "ready",
    "price": "pending",
    "safeguard": "pending",
    "faq": "off"
  },
  "publishReady": false,
  "runId": "8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75",
  "item": {
    "title": "iPhone 13 128GB, good condition, works fine",
    "description": "Selling my old phone. No box. Collection preferred.",
    "brand": "Apple",
    "model": "iPhone 13",
    "storage_gb": 128,
    "condition": "Good",
    "price": {
      "amount": 31500,
      "currency": "GBP"
    }
  },
  "pcific": {
    "release": "2.0.0",
    "category": "Phones",
    "schemaVersion": 1,
    "complete": true,
    "unfilled": [],
    "sources": {
      "/title": {
        "from": "ai"
      },
      "/storage_gb": {
        "from": "seller"
      },
      "/description": {
        "from": "ai"
      },
      "/brand": {
        "from": "seller"
      },
      "/model": {
        "from": "seller"
      },
      "/condition": {
        "from": "seller",
        "quote": "good condition"
      },
      "/price": {
        "from": "seller"
      }
    },
    "prices": {
      "/price": {
        "amount": 31500,
        "currency": "GBP",
        "display": "£315.00"
      }
    },
    "images": [
      {
        "id": "3f1c2a9e-5b7d-4e21-9c0a-6d8f4b1e7a52",
        "width": 4032,
        "height": 3024,
        "preview": "https://photos.pcific.example/preview.webp?signature=...",
        "listing": {
          "url": "https://photos.pcific.example/listing.webp?signature=...",
          "format": "webp"
        },
        "expiresAt": "2026-10-15T10:30:00Z"
      }
    ],
    "warnings": [],
    "price": {
      "status": "pending"
    },
    "safeguard": {
      "status": "pending"
    }
  }
}

{
  "status": "listing",
  "processing": false,
  "deadlineAt": "2026-10-15T10:01:00Z",
  "parts": {
    "listing": "ready",
    "price": "off",
    "safeguard": "off",
    "faq": "off"
  },
  "publishReady": true,
  "runId": "8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75",
  "item": {
    "title": "iPhone 13 128GB, good condition, works fine",
    "description": "Selling my old phone. No box. Collection preferred.",
    "brand": "Apple",
    "model": "iPhone 13",
    "storage_gb": 128,
    "condition": "Good",
    "price": {
      "amount": 31500,
      "currency": "GBP"
    }
  },
  "pcific": {
    "release": "2.0.0",
    "category": "Phones",
    "schemaVersion": 1,
    "complete": true,
    "unfilled": [],
    "sources": {
      "/title": {
        "from": "ai"
      },
      "/storage_gb": {
        "from": "seller"
      },
      "/description": {
        "from": "ai"
      },
      "/brand": {
        "from": "seller"
      },
      "/model": {
        "from": "seller"
      },
      "/condition": {
        "from": "seller",
        "quote": "good condition"
      },
      "/price": {
        "from": "seller"
      }
    },
    "prices": {
      "/price": {
        "amount": 31500,
        "currency": "GBP",
        "display": "£315.00"
      }
    },
    "images": [
      {
        "id": "3f1c2a9e-5b7d-4e21-9c0a-6d8f4b1e7a52",
        "width": 4032,
        "height": 3024,
        "preview": "https://photos.pcific.example/preview.webp?signature=...",
        "listing": {
          "url": "https://photos.pcific.example/listing.webp?signature=...",
          "format": "webp"
        },
        "expiresAt": "2026-10-15T10:30:00Z"
      }
    ],
    "warnings": []
  }
}

item is exactly your listing fields filled in, nothing added, so you can save it as it is. Everything PCIFIC adds is inside pcific. The listing can be read again for 30 minutes.

Step 6: report what the seller did

curl -X POST https://business.pcific.ai/api/v1/listings/8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75/outcome \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"published","changes":[{"field":"title","percentChanged":20}],"finalListing":{"title":"iPhone 13 128GB, good condition, collection preferred","description":"Selling my old phone. No box. Collection preferred.","brand":"Apple","model":"iPhone 13","storage_gb":128,"condition":"Good","price":{"amount":31500,"currency":"GBP"}}}'

{
  "recorded": true
}

Request fields

POST /api/v1/listings. The body is a JSON object (text in a fixed shape). At least one of notes, details or images is needed.

Send prices in details and finalListing as whole numbers in the smallest currency unit, such as 4500 pence for £45. Decimal points, exponents and text amounts are refused with 400 INVALID_FIELD.

Response fields

Starting a listing, sending answers, retrying

All three answer 202 with the same body.

Reading a listing

GET /api/v1/listings/{runId} always answers 200 for a listing that exists. Which fields are there depends on status.

Prices are whole numbers in minor units (the smallest unit of a currency, so 31500 pence is 315 pounds), with the currency code. Fields can be added at any time; ignore what you do not use.

{
  "status": "priced",
  "currency": "GBP",
  "quickSale": 29000,
  "recommended": 31500,
  "patient": 34000,
  "sources": [
    {
      "link": "https://shop-one.example/iphone-13-128gb",
      "price": 30500
    },
    {
      "link": "https://shop-two.example/apple-iphone-13",
      "price": 32500
    }
  ]
}

• The price check needs the pricing setting on. It looks for real prices of the exact item in the same condition and needs at least 2 different web pages with a real price. With fewer it answers no_price with the reason. When priced, it returns an estimate based on real prices from those pages, not a guaranteed sale price.
• A comparable with a different known brand, model, reference or variant never counts toward the two-page minimum. Orbit compares the reported identifiers with the listing fields. An absent identifier is not inferred or compared.
• When a price page cannot be downloaded, its search summary can supply the amount in your currency. Researched listing facts still need downloaded-page quotes.
• A price in another currency never counts and is never converted.
• The check runs beside drafting and Safeguard. The draft never waits for pricing. Keep polling while processing is true. A completed no_price is ready with no recommendation; not_available means the check failed. Each finished part is saved for the next poll.

Follow-up actions

The three calls that start work (start, answers, retry) count towards a test key's daily cap. Cancelling and photo uploads do not. Safeguard can review a finished Orbit listing by its runId (see the Safeguard page).

Errors

Every error is JSON with error (what went wrong), code (a fixed name to branch on), tryThis (the next step) and sometimes problems (the exact fields at fault, as paths like /images/0). A 4xx error means fix the request. A 5xx error is a problem on PCIFIC's side, so try again.

Most errors also have a docs link to their own section on Orbit errors, with the usual causes, how to fix it and a request that works. That page starts with the mistakes integrations make most often.

• Orbit errors

Orbit's errors appear in three places. Refused straight away: the call answers with an HTTP error and nothing starts. Failed later: the listing was accepted with 202, then fails, and you see it when you read the listing, where status is failed and error holds the same body. Photo errors: ordinary validation refuses the upload and saves no photos. A decoder worker failure can instead return accepted images and per-photo problems with a successful upload. The errors every address can return (UNAUTHORIZED, KEY_NOT_ALLOWED, RATE_LIMITED, OUT_OF_CREDITS and the rest) are on the Errors, limits and retries page.

Orbit photo uploads and PixelTrace checks and camera uploads share a photo capacity limit per server: 16 requests and 128 MB of uploaded bytes, with at most 2 requests and 64 MB per business across its shops and keys. These limits include receiving and processing. Content-Length reserves bytes before the body is read; without it the call reserves its maximum body size. Actual streamed bytes are counted too. Uploads must arrive within 120 seconds and wait at most 20 seconds for a photo worker. Public demos use separate capacity: 2 requests, 16 MB and one photo worker. Demo traffic cannot take paid photo places. A busy refusal does not save photos. Wait Retry-After seconds before sending the same upload again.

GET and DELETE /api/v1/images/{id} answer 404 NOT_FOUND for a photo that is unknown or has expired. Upload it again.

{
  "status": "failed",
  "processing": false,
  "deadlineAt": "2026-10-15T10:01:00Z",
  "parts": {
    "listing": "failed",
    "price": "off",
    "safeguard": "off",
    "faq": "off"
  },
  "publishReady": false,
  "runId": "8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75",
  "error": {
    "error": "Orbit made no progress for 30 seconds while writing or checking this listing and stopped. Finished parts are kept.",
    "code": "ORBIT_TIMED_OUT",
    "tryThis": "Try it again with POST /api/v1/listings/8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75/retry. If it keeps happening, contact PCIFIC support with the listing's runId."
  },
  "retry": "POST /api/v1/listings/8d0e5f12-7a3c-4b96-8e41-c2d9a6f03b75/retry"
}

A listing that fails is not charged. A test key's daily count is given back when the failure was on PCIFIC's side. A business on Bring Your Own can also see the BYO errors on that page.

Limits

Words used on this page

Related guides

• Getting started
• Build it yourself
• Set up your listing fields
• Shop configuration
• API keys and permissions
• Errors, limits and retries
• Safeguard listing check
• Monitoring and privacy
• Bring Your Own