With the Cymbio API integration, brands can effortlessly synchronize their product information, update inventory, and pull orders across a multitude of sales channels from one centralized location.
Cymbio stands as the ultimate digital growth platform, tailored specifically for brands looking to optimize their drop ship operations and supercharge their revenue streams. Brands can update inventory, push returns, update shipments, create new products, and more. By automating these tasks, your team can focus on revenue generation and core business activities.
Thanks to this formidable integration, brands can now seamlessly manage their marketplace, drop-ship, and social commerce operations. This integration opens the gateway to unprecedented growth opportunities for brands, making it easier than ever to expand reach and tap into new sales channels.
Experience the potential of Cymbio as it revolutionizes your drop ship operations, paving the way for unparalleled success and growth for your brand. Embrace the future of brand synergy and unlock the full potential of your business with API-Cymbio integration.
Staging Host: https://cymbio3-api-staging.cym.bio
Production Host: https://api.cym.bio
When you use OAuth2, the Cymbio Authentication API allows you to handle all aspects of user identification. It has endpoints for logging in, signing up, logging out, using APIs, and more.
OAuth 2.0 is the identity protocol supported by the API.
Client API credentials and Configuration values are needed to complete the integration connection setup and will be provided by Cymbio Technical Team.
To receive an access token, you need to perform the following steps:
Authorization: Bearer [your-access-token]To get authenticated, you need to have the following parameters:
| Parameters | Description |
|---|---|
| client_id | The Client ID that you receive upon account activation. |
| client_secret | The Client Secret that you receive upon account activation. |
| grant_type | client_credentials |
| scope | The scope capability of your API request for various API endpoints in a space separated list. For example, to be able to access variants and update inventory, use read:variants write:inventory For details, please see the Access Scopes section below. |
| Scope | Permissions |
|---|---|
| variants | read |
| inventory | write |
| orders | read/write |
| fulfillments | write |
The access token is only valid for 6 minutes. After that you will need to get a new token.
To synchronize product data, you have three options through Cymbio:
Options on how to sync inventory:
In any case please specify during your onboarding if you are sending full updates or deltas, and if full updates how Cymbio should treat if a product is missing from the file/feed/update.
Request Parameters
| Name | Type | Example | |
|---|---|---|---|
| warehouse_id | number | 94 | |
| id_type | “sku” | “upc” | “ean” | sku | |
| inventories | object[] | ||
| amount | number | 5 | |
| id | string | SK-3323-G | |
Response Parameters
| Name | Type | Example | |
|---|---|---|---|
| ignored_ids | string[] | [“SK-3323-G”] | |
| missing_ids | string[] | [“SK-3323-B”, “SK-3323-A”] | |
| updated_ids | string[] | [] | |
Request:
POST /v3/suppliers/1024/inventory{ "warehouse_id": 1, "id_type": "sku", "inventories": [ { "amount": 0, "id": "SK-3323-G" } ] }Response:{ "ignored_ids": [] "missing_ids": [], "updated_ids": [ "SK-3323-G" ] }
An order in Cymbio is an object that was received from a retailer or pulled from the retailer’s platform/website. An order is then linked to either one or many fulfillments, depending if the order was split to different warehouses or suppliers. As a brand you would need to grab fulfillments which you’ll need to fulfill.
Please find the shipping method codes here.
Use the following call with these query params to obtain all new fulfillments.
GET {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments?filter={"retailer_state":"ordered","fulfillment_state":"new"} (read more)
Note: if you do not add a limit and offset, the default will result in providing you the first 50 results.
To add a limit and offset, please utilize the following &limit=200&offset=0
Request:
GET /v3/suppliers/1024/fulfillments?filter={"retailer_state":"ordered","fulfillment_state":"new"}Response:
{ "id": 2086580, // Cymbio's Internal fulfillment ID "id_in_source": "100012453710", // Only used in cases where Cymbio pushes orders, not relevant "tracking_number": "1ZAA88300320803599", //If shipping label provided by Retailer "shipping_method_code": "UPS_GND", // Carrier and service level code - ask Cymbio for a complete list "created_at": "2023-07-05T15:27:33.845Z", // When captured by Cymbio "updated_at": "2023-07-05T22:45:33.681Z", "supplier_invoice_id": null, // If updated by the supplier, relevant from Dropship orders "warehouse_id": 57, // Supplier's WHS ID within Cymbio's Database "order_id": 2115443, // Order ID in Cymbio's Database, an order can have multiple fulfillments "packing_slip_link": "https://docs.cym.bio/1894/d2ffd4ddd7f5bdfb.pdf", "shipping_paid": "0", // By end-consumer "shipping_tax_paid": 0, // By end-consumer "supplier_id_in_source": "100012453710", // Used in cases if your ID is different than Cymbio's ID - Not Relevant "shipping_duties": 0, // By end-consumer "shipping_discount": 0, // Provided to consumer by retailer "duties_tax": 0, // By end-consumer "fulfillment_lines": [ { "id": 3016050, // Line ID "handling_price": 0, // If applicable "shipping_price": 0, "discount_amount": 0, "commission_fee": 0, "quantity": 1, "currency": "USD" "unit_price": 125, // Price per item, based on your commercial agreement with the sales channel and configured within Cymbio's platform. "variant_id": 2149736, // Cymbio's Variant ID "variant": { "sku": "22F1TP23PL-BLACK-XS", "upc": "728870420437" }, "line_tax": null, // Tax of entire line "billed_amount": 130, // The amount paid by the end-consumer for the item, after discounts and before taxes "box_type": "101" // If provided by the retailer, the suggested box type to use when shipping the product } ], "retailer_order_id": "100012453710", // PO# "shipping_address": { "first_name": "Name", "last_name": "Last Name", "address1": "70 S CHERRY ST", "address2": "", "country": "US", "city": "DENVER", "state": "CO", "zip_code": "80246-1029", "phone_number": "800555555", "email": null, "company_name": null }, "billing_address": { "first_name": "Name", "last_name": "Last Name", "address1": "70 S CHERRY ST", "address2": "", "country": "US", "city": "DENVER", "state": "CO", "zip_code": "80246-1029", "phone_number": "800555555", "email": null, "company_name": null }, "retailer_id": 1894, // Cymbio's internal Retailer ID "retailer_name": "Nordstrom - Carter's", "retailer_erp_id": null, // Retailer ID in the supplier's internal system "retailer_state": "ordered", // Status of order on Retailer side - Can be "canceled" "notes": [ { "name": "DSCO Order ID", // Based on each retailer and their notes, used for packing slips "value": "580357395" } ], "fulfillment_state": "completed", // The state of the fulfillment "shipper_account_type": null, // For 3rd party billing - Carrier "shipper_account": null, // For 3rd party billing - Account Number "is_pre_order": false, "conversion_rate":0, "sales_order_number": 0, "sales_division_code": "string", "order_processing_state": "string", "expired": false }
After capturing a fulfillment we expect you to accept it by using the following call
PUT {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments/{{fulfillment-id}}/setStatus/accepted
(read more)
Note: Fulfillments you accept won’t appear anymore on the GET fulfillments call as their status will be changed from “New”.
Request:
PUT /v3/suppliers/1024/fulfillments/2086580/setStatus/accepted{ "supplier_order_id_in_source": "string" }Response:{ "success": true }
After acceptance, you can send ASN (Advanced shipment Notice) per order or in bulk and also reject an order or line/s.
You can send Shipping Notice (ASN) for one or multiple fulfillments:
POST {{api-host}}/v3/suppliers/[{supplier-id}}/fulfillments/shipments
(read more)
We can support SKU, UPC, EAN, or your internal identifier for a product.
If there are 2 fulfillments, id 161 and 117, where 161 was split into 2 shipments and 117 is only 1 shipment.
Request:
POST /v3/suppliers/1024/fulfillments/shipments[ { "id": 161, "shipments": [ { "items": [ { "sku": "440012", "quantity": 1 }, { "upc": "293321321288", "quantity": 1 } ], "trackingNumber": "TRACKING1", "shippingMethodCode": "UPS", "returnTrackingNumber": "RETURNTRACKING1" }, { "items": [ { "sku": "44624", "quantity": 1 }, { "id_in_source": "abcde", "quantity": 1 } ], "trackingNumber": "TRACKING2", "shippingMethodCode": "USPS" } ] }, { "id": 117, "shipments": [ { "items": [ { "sku": "44630", "quantity": 4 } ], "trackingNumber": "TRACKING3", } ] } ]Response:{ "success": true }
You can reject multiple fulfillments or specific lines/quantities (cancel or short):
POST {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments/rejections
(read more)
We can support SKU, UPC, EAN, or your internal identifier for a product.
Request:
POST /v3/suppliers/1024/fulfillments/rejections[ { "id": 161, // Fulfillment id "rejectId": "123", // Must be unique per each API call "items": [ { "sku": "440012", "quantity": 1 }, { "sku": "440013", "quantity": 1 }, { "sku": "44624", "quantity": 1 } ] }, { "id": 117, // Fulfillment id "rejectId": "124", // Must be unique per each API call "items": [ { "sku": "44630", "quantity": 4 } ] } ]Response:{ "success": true }
You can capture fulfillments that have been canceled by the retailer, and approve or reject them.
GET {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments?filter={"fulfillment_state":"cancelling"}
(read more)
Note: After capturing cancellation you can either approve or reject a cancellation
PUT {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments/{{fulfillment-id}}/setStatus/canceled
(read more)
PUT {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments/{{fulfillment-id}}/setStatus/cancellation_not_allowed
(read more)
If you would like to utilize your own Invoice ID for Dropship retailers, use the following call to send your Invoice ID:
PUT {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments/{{fulfillment-id}}
(read more)
Note: this needs to be sent prior to any Fulfillment being sent or we will utilize the original PO Number as the Invoice ID.
If you or your warehouse would like to pull in only the fulfillment documentation, use the following call to pull in only the documentation from the order:
GET {{api-host}}/v3/suppliers/{{supplier-id}}/fulfillments-documents?identifier_type=fulfillment_id&identifiers={{fulfillment-id}}
(read more)
Note: this only brings back the documentation for each fulfillment. If you would like to pull multiple fulfillments, utilize a comma in between each fulfillment. {example: identifiers=31566,31565}
Cymbio provides the ability for suppliers to obtain from the sales channel information about returns on the way back to their warehouse.
If one of the Sales Channels you are live with provides visibility into the Customer Returns back to your warehouse, you can utilize this endpoint to obtain this information.
Using the Reverse Logistics Return (RLR) API:
GET {{api-host}}/v3/suppliers/{{supplier-id}}/reverse-logistics-returns?from_date=YYYY-MM-DDTHH:mm:ss.sss&to_date=YYYY-MM-DDTHH:mm:ss.sss
(read more)
Query Parameters:
| Name | Type | Example |
|---|---|---|
| from_date | Date (YYYY-MM-DDTHH:mm:ss.sss) | 2024-01-01T00:00:00.000 |
| to_date | Date (YYYY-MM-DDTHH:mm:ss.sss) | 2024-01-01T23:59:59.999 |
| limit | number | 200 |
| offset | number | 0 |
Request:
GET /v3/suppliers/1024/reverse-logistics-returns?from_date=2024-01-01T00:00:00.000&to_date=2024-01-01T23:59:59.999Response:{ "id": 1002, "retailer_name": "Macy's", "retailer_erp_id": "macys-1234", // Retailer ID in the supplier's internal system, "retailer_id": 123, "fulfillment_ids": [123], "retailer_order_id": "PO-3223D", "retailer_return_order_id": 103, "reverse_logistics_return_lines": [ { "variant": { "sku": "440012", "upc": "0799439112766", "ean": "00799439112766" "quantity": 1 }, } ], "tracking_number": "1Z008DD082373", "reason_type": "item_damaged", "return_method": "return_to_vendor", "reason_text": "Item has water damage" }
Available reason types for RLR notifications:
Available return methods for RLR notifications:
Sending a notification that a return was made and that the customer can be refunded can be done by the following method:
Using the return API:
POST {{api-host}}/suppliers/{{supplier-id}}/fulfillments/{{fulfillment-id}}/returns
(read more)
| Name | Type | Example | |
|---|---|---|---|
| reason_code | string | damaged | |
| return_id | string | DKJS822 (Must be unique per each API call) | |
| reason | string | Package had water damage | |
| return_lines | |||
| quantity | number | 1 | |
| status | “accepted” | “declined” | accepted | |
| sku | string | XXP3442 | |
| upc | string | 0799439112766 | |
| fulfillment_line_id | number | 100203 | |
Request:
POST /v3/suppliers/1024/fulfillments/10034/returns{ "reason_code": "damaged", "return_id": "DKJS822", "reason": "Water damage", "return_lines": [ { "quantity": 1, "sku": "XXP3442", "status": "accepted" } ] }Response:{ "success": true }
In case you wish to push a dispute, meaning you want the retailer not to refund the end customer, use the same endpoint as described above, and send the status=declined in the body instead of accepted.
For help – please reach out to support@cym.bio.
The $5 Trillion Wake-Up Call: Is Your Brand Ready for Agentic Commerce? In a recent Forbes feature, Cymbio Co-Founder & CEO Roy Avidor […]
Expanding the Alliance: Cymbio and Stripe Form a new Partnership for Agentic Commerce Agentic Commerce is transforming the way people shop online. As […]
Cymbio Selected As Premier Strategic Partner for PayPal’s New Agentic Commerce Services The architecture of online retail is undergoing its most significant shift […]