Example base: https://idahopawn.com/api/integrations/listings/v1. This host serves documentation only.
GlobalOS Inventory API v1
Send inventory from PawnOS or another system to a tenant’s shopping website. New items remain private until an employee reviews and publishes them.
Download OpenAPI specification
1. Connect
A tenant owner opens Stores & employees → Inventory connections, adds a system, and creates an expiring key for selected stores. Keep the key on your server. Never put it in a browser, photo URL or query string.
Authorization: Bearer gos_live_YOUR_KEY Content-Type: application/json
Use the tenant’s own website origin, for example https://idahopawn.com. All endpoints start with /api/integrations/listings/v1. Requests are HTTPS only. Limit: 120 requests per minute per key.
2. Get store IDs
GET /api/integrations/listings/v1/stores
{
"stores": [{"id":"STORE_UUID", "name":"Boise"}]
}Map your store number to the returned GlobalOS store UUID once. A key cannot write outside its selected stores.
3. Send an item or update
POST /api/integrations/listings/v1/items
{
"eventId": "pawnos-EX100-v1",
"sourceVersion": 1,
"storeId": "STORE_UUID",
"externalItemId": "EX100",
"sourceProductId": "PROD100",
"title": "Cordless drill with charger",
"description": "Tested. Includes charger and one battery.",
"category": "tools",
"condition": "good",
"priceCents": "6500",
"currency": "USD",
"quantity": 1,
"status": "available",
"photos": [{"id":"front", "url":"https://media-pos.pawnos.com/prod/your-photo.jpeg"}]
}202 means the event was received, not that the item is publicly listed. The response includes stable correlation IDs:
{
"importItemId": "IMPORT_UUID",
"listingId": "GLOBALOS_LISTING_UUID",
"externalItemId": "EX100",
"storeId": "STORE_UUID",
"sourceVersion": 1,
"reviewStatus": "pending",
"listingStatus": null,
"listingUrl": null,
"updatedAt": "2026-10-22T15:00:00Z",
"duplicate": false
}Save listingId alongside your item number. The listing ID is reserved before publication and stays the same. externalItemId is unique within a system and store; keep it stable even if a title changes. The public URL appears only after publication on a verified tenant website.
| Field | Rules |
|---|---|
| eventId | Unique event identifier per connection, up to 128 characters. Retry the exact payload with the same ID after a timeout. Changed payloads require a new ID. |
| sourceVersion | Positive, increasing integer per item. A durable item revision or monotonically increasing update timestamp in milliseconds works. Older or reused versions return 409. Retrying the original event remains safe. |
| storeId / externalItemId | Required on every POST. External IDs are case-sensitive, up to 128 characters. Do not send the same physical item to multiple stores unless it is intentionally a separate listing. |
| title / category / condition / priceCents | Required for the first event. Title 3–160 characters. Price is an integer string in USD cents, e.g. "6500" = $65.00. Zero stages an item with no usable selling price; publication requires a positive price. |
| description | Plain text, up to 4,000 characters. Staff can polish it before publication. |
| category | electronics, tools, handbags, firearms, gold, silver, jewelry, watches, equipment, other |
| condition | new, excellent, good, fair, for-parts |
| status | available, reserved, sold, unavailable, on_loan, awaiting_approval, deleted |
| quantity | Integer 0–1,000,000. Zero removes the item from sale. Defaults to 1 for new items. An available quantity does not automatically publish an item. |
| sourceUrl / sourceProductId / sourceUpdatedAt | Optional staff reference link (HTTPS), product code and ISO 8601 timestamp. Not copied to the public description. |
| attributes | Optional object with brand, model, metal, purity and decimal-string weightGrams. |
| photos | Up to 12 unique source photo IDs; optional HTTPS URL per photo. Omit to keep the previous photo manifest. An included array replaces the manifest. Use a new URL or photo ID when replacing image content. Uploaded images must be JPEG, PNG or WebP, ≤5 MB each. |
Send only public product information. Customer names, phone numbers, internal cost, loans, payouts, notes and serial numbers are deliberately not accepted as fields. Keep those details out of the title, description and photos too. Listing approval does not grant Google Merchant approval; existing advertising-policy review remains separate.
4. Update price or stock
POST /api/integrations/listings/v1/items
{
"eventId":"pawnos-EX100-v2", "sourceVersion":2,
"storeId":"STORE_UUID", "externalItemId":"EX100",
"priceCents":"5900", "status":"available", "quantity":1
}Omitted fields retain their previous values. For approved, published listings, price updates are automatic unless the owner turns that option off. New titles, descriptions, categories, conditions, attributes and photos wait for review; the current public content stays in place meanwhile. Unavailable, on-loan, reserved, sold, deleted or zero-quantity stock is removed from public sale immediately. Returning stock automatically restores a previously approved listing when only its availability changed. Items with pending content/photos or employee changes made while hidden still need review. “Deleted” archives the listing; it does not erase the correlation record.
5. Photos
GlobalOS imports links hosted on media-pos.pawnos.com. Other providers can have their photo host connected, or upload bytes directly. Redirects are not followed. Files remain private until approved. A photoWarnings array means the item was accepted but one or more photos need a retry or direct upload.
POST /api/integrations/listings/v1/photos?importItemId=IMPORT_UUID&sourcePhotoId=front&sourceVersion=1 Authorization: Bearer gos_live_YOUR_KEY Content-Type: image/jpeg [raw JPEG bytes, not JSON or multipart]
Include the source photo ID in the item’s photos array first. Upload against its current sourceVersion. Retrying identical bytes is safe. Different bytes at the same sourceVersion return 409; send a new item version first. All declared photos must finish before approval.
6. Read review and publication results
GET /api/integrations/listings/v1/items?listingId=GLOBALOS_LISTING_UUID or GET /api/integrations/listings/v1/items?storeId=STORE_UUID&externalItemId=EX100
The same receipt shape shows the latest review status (pending, approved, rejected, held), actual listing status and public URL. This version provides an inbound webhook endpoint and status polling; it does not push an outbound callback to PawnOS. Poll pending items periodically, and refresh the result when your operator opens the item. Review screens show the source item number separately from the editable public item number.
Errors and retries
| Status | Meaning |
|---|---|
| 200 / 202 | 200 read or duplicate event; 202 newly accepted inventory event. Photos return 200 when ready. |
| 400 / 415 | Invalid fields, missing first-event fields, or incorrect content type. Correct the request. |
| 401 / 403 | Missing/invalid key, revoked/expired key, paused connection, tenant mismatch, disabled listings or insufficient scope/store access. |
| 404 | No matching item visible to this key. |
| 409 | Reused event ID with changed data, stale sourceVersion or different photo bytes at the same version. |
| 429 | Rate limit. Respect Retry-After. |
| 503 / timeout | Retry the exact event ID, version and payload with backoff. Do not create a new item number. |
Never infer publication from a successful upload. Check listingStatus and listingUrl. No customer messages or outbound callbacks are sent by the ingestion endpoint.