Store

Merchant systems API

Connect your systems to this store

Read paid orders, hear about every change by webhook, and send back stock levels, shipments, deliveries, returns that arrived, and lines you can't fill. For warehouses, 3PLs, ERPs and shipping platforms.

Get started

Every request goes to this store's own address with a system key: Authorization: Bearer pgi_…. Store staff create keys in the console (Systems → Connect a system), choosing what the key may do. To try it first, get a sandbox key.


  

Keys and scopes

Each system has its own key, kept by the store only as a fingerprint and shown once. A key carries scopes, and a request outside them is refused with 403 scope_missing:

Staff can pause a key, resume it, or replace it (the old key stops at once). A paused, replaced or expired key gets 401 unknown_key.

A point of sale

A register in the merchant's showroom connects with the pos scope, so the showroom and the web sell from one shelf. Send each counter sale or return to POST /integrations/v1/stock/adjust as changes (-2 sold, +1 back), never as a count: a count from the register would overwrite units that online orders have just reserved. Card payments stay at the register; send the total if you want it in the merchant's showroom channel.

Shoppers' agents can choose pickup at checkout, like any delivery option; it's never chosen for them. A pickup order's delivery starts with "Pickup at". When it's handed over, send POST /orders/{order_id}/collected. When someone brings a web or agent order back to the counter, send POST /orders/{order_id}/returned-in-person: the store refunds it the way it was paid and restocks it in one step.

Event ids and retries

Every update you send carries an event_id you choose (6–100 letters, digits, . _ : -). Send the same id again and nothing changes: you get the first answer back with "replayed": true. So when a request times out, retry it with the same id. A 500 not_applied means nothing changed, and the same id is safe to retry.

Errors

Every error is JSON with a stable code, a message written for people, and sometimes the field at fault. Act on the code, show the message.

Paging through orders

GET /integrations/v1/orders returns the oldest change first. Keep the next_cursor from each page and send it back unchanged; when has_more is false you're caught up. To pick up new changes later, call again with your last cursor, or with updated_since. Paying, shipping, delivering, cancelling and every return step count as changes.


  

Webhooks

Give a key the orders scope and a webhook address, and the store POSTs every order event to it: . Each event's data is the order as the API returns it, plus what the event is about.

Check the signature

Each webhook carries Pegasus-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of "<t>.<raw body>" with your webhook secret. Reject a missing or wrong signature, and anything older than five minutes.

import crypto from "node:crypto"

export function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "")
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false
  const want = crypto.createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]))
}

Answering, retries and duplicates

Answer with any 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then marked failed; store staff can resend it from the console. The same event can arrive more than once: de-duplicate on its id.

Versions

Every response carries Pegasus-Api-Version. Within v1, changes only add: new fields, new optional parameters, new events, new error codes. Ignore fields you don't know. Anything that would break a working integration goes to /integrations/v2, announced here at least 90 days before v1 changes.

Reference

Loading…