Scopes
The permissions an app can ask for, what each one unlocks in the API and which webhook events it entitles you to.
A scope is what your app asks for and what the seller approves. The same table decides three things: what the consent page says, which endpoints answer, and which events are delivered to you. Reading a thing and being told it changed are the same permission.
| Scope | Seller reads on the consent page | Endpoints | Events |
|---|---|---|---|
profile:read | Read your seller name, email and countries | GET /me | — |
catalogue:read | Read your products and prices | GET /products, GET /products/{id}, GET /cod-drop/catalog, GET /cod-drop/catalog/{productId} | product.changed, product.removed, price.changed, adoption.created · adoption.updated · adoption.removed, cod_drop.catalog_changed (enabled apps only) |
products:write | Create and update products and boutiques on your behalf | POST /products, PUT /products/{id}, GET /stores, POST /stores | — |
orders:write | Create orders on your behalf and take over your manual orders (with their customer details) | POST /orders, GET /orders/claim-direct/preview, POST /orders/claim-direct | The order events — for orders your app created or claimed only |
orders:read | Read back the orders it created, to check nothing was missed | GET /orders, GET /orders/{externalId} | — |
cod_drop:write | Browse the COD Drop catalogue and adopt products on your behalf | POST /cod-drop/adoptions, PUT /cod-drop/adoptions/{productId}, DELETE /cod-drop/adoptions/{productId} | product.changed, product.removed, adoption.created · adoption.updated · adoption.removed |
orders:details — restricted | Internal order details: call-centre and delivery statuses, fees, weights, deliveryman, warehouse, invoicing | Adds ColiSwift’s internal fields to the Order | Reserved order events (with orders:write) |
products:details — restricted | Internal product details: cost and creator, discounts, free shipping, weights, barcodes, notes | Adds ColiSwift’s internal fields to the Product and the COD Drop product | — |
Restricted scopes
Two scopes are restricted: ColiSwift adds them to an app only, on request (go live), and a sandbox developer app cannot select them (400 SCOPE_NOT_SELF_SERVICE). Most integrations need neither: an app learns the seller’s products, prices and orders, not ColiSwift’s internals.
Calling without the scope
A call your token is not entitled to answers 403 and names the scope to add to your registration:
{
"error": {
"message": "This application was not granted the permission this call needs.",
"code": "INSUFFICIENT_SCOPE",
"required": [
"orders:write"
]
}
}How scopes filter events
- An event is delivered to your app for a seller when the app is active, the seller’s connection is live, the seller’s account is active, the connection’s scopes entitle the event type (counting only scopes your app is still allowed), your app has a webhook URL, and your event filter is empty or lists that type.
product.changedis entitled bycatalogue:read(the seller’s own products and adopted ones) and bycod_drop:write(adopted ones). There is one event name for both: an app holding onlycod_drop:writereceivesproduct.changedfor own products too.adoption.created/adoption.updated/adoption.removedare entitled by either scope as well.lead.*events are further narrowed to the app that created the order: another app connected to the same seller never sees your orders, and you never see theirs or the seller’s manual orders (unless you claim them).