Events
The events Commerce Orbit sends to Orbit Exchange when products, stock, collections, orders and the MAM connection change, what each carries, and how they are delivered. The same events can go to your own systems as webhooks.
Reference4 min read
When something changes in Commerce Orbit, such as a product's price or an order being paid, it records an event and sends it to Orbit Exchange, the hub that connects Orbit's products. Other satellites react to them there, and Orbit shows them under Exchange.
Events go to Orbit Exchange, where Orbit's products use them, and to the webhooks you add for your own systems:
- CMS Orbit refreshes website pages that show a product or collection when it changes. See Show your products on your website.
- Insights Orbit can count
commerce.order.placedas a goal with revenue. See Orbit connections.
To keep your own website current, read the storefront API and cache its answers for a short time.
The envelope
Every event has the same outer shape as events from Orbit's other satellites. Only data differs.
idtypecommerce.order.paid.versiondata shape. It only goes up for a change that could break a receiver. All are 1 today.timesourcecommerce.sequencetenant.organisationIdtenant fields are null.data.shopIdsubject.resourceTypeproduct, collection, order or mam.subject.idactor.typeuser when someone on your team did it, system when a shopper, Stripe or Commerce Orbit did, such as a checkout, a payment or a MAM sync.actor.idnull for system.data| Field | What it holds |
|---|---|
id | A unique ID (UUID) for this event. Use it to spot duplicates. |
type | The event name, such as commerce.order.paid. |
version | The version of this event's data shape. It only goes up for a change that could break a receiver. All are 1 today. |
time | When it happened, in UTC. |
source | Always commerce. |
sequence | A number that goes up with each event from your organisation. |
tenant.organisationId | Your organisation. The other tenant fields are null. |
data.shopId | The shop the event happened in, when your organisation has more than one. |
subject.resourceType | product, collection, order or mam. |
subject.id | The ID of what changed. |
actor.type | user when someone on your team did it, system when a shopper, Stripe or Commerce Orbit did, such as a checkout, a payment or a MAM sync. |
actor.id | The person's ID, or null for system. |
data | The details below. |
The events
commerce.product.publishedcommerce.product.unpublishedcommerce.product.changedcommerce.stock.changedcommerce.collection.changedcommerce.order.placedcommerce.order.paidplaced.commerce.order.fulfilledcommerce.order.refundedcommerce.order.cancelledcommerce.order.editedcommerce.return.requestedcommerce.return.approvedcommerce.return.rejectedcommerce.return.receivedstatus is refunded when it was refunded in the same step.commerce.mam.statusok, degraded, down and off.| Event | When |
|---|---|
commerce.product.published | A product becomes active. |
commerce.product.unpublished | An active product becomes a draft, is archived or moves to the bin. |
commerce.product.changed | An active product is saved, or MAM changes its price. |
commerce.stock.changed | Stock changes: by hand, at checkout, when an unpaid order is cancelled, on a refund with restock, or from a MAM sync. |
commerce.collection.changed | A collection is added, saved or moved to the bin. |
commerce.order.placed | An order is paid by card or placed on invoice. |
commerce.order.paid | An order is paid: by card at checkout, or an invoice marked as paid. A card order sends this right after placed. |
commerce.order.fulfilled | Items on an order are marked as sent, in full or in part. |
commerce.order.refunded | Money is refunded, from Commerce Orbit or in Stripe. |
commerce.order.cancelled | Your team cancels an order. |
commerce.order.edited | Your team changes the items, quantities or discount on a placed order. The data has the new total. |
commerce.return.requested | A customer asks to return items, or your team starts a return. |
commerce.return.approved | Your team approves a return. |
commerce.return.rejected | Your team rejects a return. |
commerce.return.received | The returned parcel arrives. status is refunded when it was refunded in the same step. |
commerce.mam.status | The MAM connection is switched on or off, or its status changes between ok, degraded, down and off. |
Product events
data has productId, slug and title:
{ "productId": "6650f1c2a9e4b3d2c1f0e9b1", "slug": "tind-2-tent", "title": "Tind 2 tent" }Stock events
data has productId, slug and variantIds, the variants whose stock changed. Read the product to get the new numbers.
Collection events
data has collectionId, slug and title.
Order events
data has orderId, reference, status (open or cancelled), paymentStatus, fulfilment, total, currency, lines (how many lines) and source (where the cart came from, such as https://northwilds.com, or null):
{ "orderId": "6650f1c2a9e4b3d2c1f0eb42", "reference": "NW1042", "status": "open", "paymentStatus": "paid", "fulfilment": "unfulfilled", "total": 46700, "currency": "EUR", "lines": 3, "source": "https://northwilds.com"}Amounts are whole minor units: 46700 with EUR is €467.00. Events never carry customers' names, emails or addresses.
Orders cancelled by Commerce Orbit because the payment wasn't finished in time send no commerce.order.cancelled, as they were never placed.
Return events
data has returnId, reference (such as R1001), orderId, orderReference, status, items (how many items), refundAmount (or null) and currency.
MAM events
data has status and message, MAM's reason when something failed, or null.
Delivery
Events are sent at least once. Each one waits in Commerce Orbit until Orbit Exchange accepts it. If Exchange can't be reached, Commerce Orbit tries again after 2 minutes, then waits twice as long each time, up to 12 hours between tries, for 12 tries in all. After that the event is no longer sent. Because a try can succeed even when the answer is lost, the same event can arrive twice: use id to spot it.
Was this page helpful?