Custom Marketplace
Connect your own website, or any marketplace with an HTTP API, by mapping O2M's product fields to the JSON it accepts.
Overview
A Custom Marketplace connection links your own website, or any marketplace with an HTTP API, to O2M: you map O2M's product fields to the JSON it accepts, list products on it from the listing form, and its orders come back to O2M.
Why use it
- Sell on your own website or a marketplace O2M has no connector for, from the same product list.
- Keep stock and product changes in step without a developer writing an integration.
- Bring its orders into O2M to be packed and shipped like any other.
Before you begin
- Custom Marketplace is turned on for your company.
- Their API documentation and an API key.
Before you begin
- Custom Marketplace is available for your company. The platform administrator turns it on and sets how many connections you can add.
- Their API takes one JSON call to create a product, one to update it and one to remove it, over https://.
- Their API key (or key and secret, username and password, or bearer token), and their API documentation with a sample product body.
- In O2M: the Admin or Billing admin role to enter keys and the address. Other settings need Set up custom marketplace connections and mappings.
Good to know APIs that need a login page (OAuth), several calls to create one product, or image files uploaded separately are not supported.
Add a connection
- 1Open Settings → Marketplace and Integrations → Marketplaces and click Set up on the Custom Marketplace card.
- 2Click Add connection, give it a name such as
Brand website, and click Add. You can rename it at any time; the new name shows everywhere in O2M.
Address and keys
- 1On the Connection tab, type the Base URL of their API, such as
https://api.yourshop.com/v1. - 2In Their API checks keys by, choose how their API expects the key, and the header name if it asks for one.
- 3Click Save, then enter the key under Keys and click Save keys.
- 4Each time, O2M asks for your two-factor code before saving.
Important Keys are stored encrypted and never shown again; only their last four characters are. They are tied to the base URL: if you change it to another address, the saved keys are removed and must be entered again.
Endpoints
On the Endpoints tab, enter the method and path of each call. {external_id} is filled with their product ID, {sku} with the SKU and {order_id} with their order ID.
| Call | Needed | Used when |
|---|---|---|
| Create product | Yes | A product is listed for the first time |
| Update product | Yes | A listed product changes in O2M |
| Remove product | Yes | You unlist the product |
| Stock change | No | Stock changes. Without it, O2M sends a full product update |
| Shipment | No | A parcel leaves, if Tell their API when a parcel ships is ticked |
| Health check | No | You click Health check on Test & logs |
Under Their answer, say where their reply has the new product's ID (for example product.id) and, for products with variants, the list of variants. O2M keeps these IDs so later updates go to the same product.
Map O2M fields to their JSON
On the Mapping tab, write the JSON their API accepts. Where a value should come from O2M, type @ and pick the field, or click it in the list on the left. "name": "@product.title" sends the product's title.
- Variants: a list whose first item has
"@each": "variant"is repeated for every variant. Use@variant.option.sizefor a variant's size, colour and so on. - Images:
@product.imagessends a list of image links; a list with"@each": "image"sends one object per image with@image.url. - Fixed values: type the value itself, such as
"status": "active". - Paste a sample: paste a sample body from their documentation and click Match fields. O2M fills in the fields it recognises by name; check the rest.
Under Keys, click a key to change how its value is sent: as text, a number or true/false, rupees in paise, a list joined into one value, a default when empty, or a value map such as XL=extra-large. Tick Required for keys their API cannot do without.
Click Preview to see the exact request for one of your products. Leave MasterProductID empty to use your latest product. Keys show as dots.
Use the menu at the top to write separate bodies for Product update, Stock change, Remove product and Shipment. Without a separate update body, the new product body is used. History keeps the last 20 saved versions.
Turn it on and list products
- 1On Test & logs, click Health check, then Show the request and Send a test product to try a real call.
- 2Click Turn on at the top. O2M checks that the address, keys, the three needed endpoints and the product mapping are in place.
- 3Open a product's listing form: the connection is listed under its name with your other channels. A key you marked required that the product has no value for is asked for on its card.
After that, a saved change to the product updates it on their side, stock changes are sent on their own, and unlisting removes it. Every call is in Test & logs for 30 days, and each change to the connection is in Request History.
Orders from their system
On the Orders tab, copy the address their system should send orders to. Click Make the signing secret (two-factor code needed) and give the secret to their developer: it is shown once. Each request is signed, and O2M refuses one that is not signed or is older than 5 minutes.
- O2M's order format: their system sends orders as shown on the tab (API documentation).
- Their own format: choose it, paste a sample order and click Match keys, then check where each value is: the order ID, the lines and each line's SKU and quantity are needed.
- A status value you list under Cancelled when status is cancels an order sent before.
Orders appear in Orders under the connection's name. The same order sent twice is saved once, and returns wait for your team like any other.
Pause or delete
Pause stops all calls and refuses its orders until you turn it on again. Delete connection on the Connection tab removes its keys at once; its orders and history stay in O2M.