Cymbio API for Retailers

Get Started

Authentication

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.

To receive an access token, you need to perform the following steps:

Contact our team to receive the following API credentials and configurations values: Client ID, Client Secret, Supplier ID, and Retailer ID.
Set your Grant Type to client_credentials.
Set the scope definitions per the table below.
Request an Access Token by sending a POST request to {{api-host}}/oauth/token
Receive an Access Token.

Authentication Parameters

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. For example: read, write, etc. For details, please see the Access Scopes section below.

Access Scopes

Each API has a scope definition that you need to request based on the calls, but the relevant ones are:

Scope	Permissions
variants	read
retailers	read
orders	read
orders	write

The access token is only valid for 6 minutes. After that you will need to get a new token.

Products/Inventory

How can you pull products/variants copy/imagery/pricing and inventory?

We offer one single end-point to consume product data and inventory, all the products you’ll be exposed to are ones that the brand or brands approved for you to use.

GET {{api-host}}/v3/retailers/{{retailer-id}}/variants?service_type=ecommerce&limit=1000&offset=0 (read more)

Make sure any additional call, you change the offset to get the next page where 0 = first page, 1000 = 2nd page, and so on.

View ExampleMore

Request:

GET /v3/retailers/3/variants?service_type=ecommerce&limit=1000&offset=0

Response:

[
    {
        "id": 15383,
        "sku": "32291-06537-10",
        "upc": "888731282960",
        "ean": null,
        "retailer_sku": "512341-2443",
        "options": {
            "size": "10",
            "color": "Rose Gold"
        },
        "properties": {
            "type": [
                "Slide"
            ],
            "year": [
                "2017"
            ],
            "color": [
                "Rose Gold"
            ],
            "season": [
                "FW"
            ],
            "category": [
                "Melissa"
            ]
        },
        "currency": "USD",
        "supplier_id": 1,
        "supplier_name": "Melissa",
        "retail_price": 850000,
        "model": "32291-06537",
        "title": "BEACH SLIDE SHINE",
        "description": "The classic Beach Slide has gotten extra shimmery this season in these new exciting colorways.",
        "description_extra": "<ul><li>100% Recycled PVC</li><li>Durable, flexible and hypoallergenic</li><li>Bubble gum scent</li><li>Made in Brazil</li></ul>",
        "description_bullets": null,
        "images": [
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/original/32291-06537-8708f25c90f4598d8aeed3fc1ebf1df4.png",
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/original/32291-06537-8b6cc572ebb099c4b0e188cf37646f86.png",
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/original/32291-06537-d48495332b9e962349b3b27d981f0e8c.png",
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/original/32291-06537-c48413d20c2706d6ec6047bbba7de7c0.png"
        ],
        "retailer_title": "BEACH SLIDE - hi",
        "retailer_description": "The classic Beach Slide has gotten extra shimmery this season in these new exciting colorways. ",
        "retailer_description_extra": "<ul>\n  <li>100% Recycled PVC</li>\n  <li>Durable, flexible and hypoallergenic</li>\n  <li>Bubble gum scent</li>\n  <li>Made in Brazil</li>\n</ul>",
        "retailer_description_bullets": null,
        "special_sale_price": null,
        "special_sale_price_start": null,
        "special_sale_price_end": null,
        "available_inventory": 0,
        "square_images": [
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/square_300/32291-06537-8708f25c90f4598d8aeed3fc1ebf1df4.png",
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/square_300/32291-06537-8b6cc572ebb099c4b0e188cf37646f86.png",
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/square_300/32291-06537-d48495332b9e962349b3b27d981f0e8c.png",
            "https://s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/square_300/32291-06537-c48413d20c2706d6ec6047bbba7de7c0.png"
        ]
    }
]

Response ParametersMore

Name		Type	Sample	Description
id		number	15383	Cymbio’s unique ID
sku		string	32291-06537-10	Product SKU
upc		string	888731282960	Product UPC
ean		string	null	Product EAN
retailer_sku		string	512341-2443	Product’s SKU on the retailer platform
options		object		An object of options specifying the uniqueness of this variant, like size, color, width, etc.
	size	number	10	The size of the variant
	color	string	Rose Gold	The color of the variant
properties		object		An object of attributes
	type	string	Slide
	year	number	2017
	color	string	Rose Gold
	season	string	FW
	category	string	Melissa	Product’s Category
currency		string	USD	Main Currency
supplier_id		number	1	The Cymbio ID of the brand/vendor/supplier that owns this product
supplier_name		string	Melissa	The name of the brand/vendor/supplier that owns this product
retail_price		number	850000	retail price in cents in the currency specified above
model		string	32291-06537	The parent SKU/Style of this variants
title		string	BEACH SLIDE SHINE	Product title
description		string	The classic Beach Slide has gotten extra shimmery this season in these new exciting colorways.	Product short description
description_extra		string	<ul><li>100% Recycled PVC</li><li>Durable, flexible and hypoallergenic</li><li>Bubble gum scent</li><li>Made in Brazil</li></ul>	Additional description in HTML format
description_bullets		string[]	null	Additional description in bullets
images		string[]	[https//s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/original/32291-06537-8708f25c90f4598d8aeed3fc1ebf1df4.png]	An array of images
retailer_title		string	BEACH SLIDE – hi	Used in cases the title was overwritten by the retailer to comply with retailer’s romance (Done in the UI only)
retailer_description		string	The classic Beach Slide has gotten extra shimmery this season in these new exciting colorways.	Used in cases the title was overwritten by the retailer to comply with retailer’s romance (Done in the UI only)
retailer_description_extra		string	<ul><li>100% Recycled PVC</li>\n <li>Durable, flexible and hypoallergenic</li>\n <li>Bubble gum scent</li>\n <li>Made in Brazil</li></ul>	Used in cases the title was overwritten by the retailer to comply with retailer’s romance (Done in the UI only)
retailer_description_bullets		string[]	null	Used in cases the title was overwritten by the retailer to comply with retailer’s romance (Done in the UI only)
special_sale_price		number	null	Sale price in cents
special_sale_price_start		date	null	Sale price start date
special_sale_price_end		date	null	Sale price end date
available_inventory		number	0	Amount of unit available to sale
square_images		string[]	[https//s3.amazonaws.com/cymbio-3-staging/Brands/Melissa/Images/square_300/32291-06537-8708f25c90f4598d8aeed3fc1ebf1df4.png]	Array of thumbnail images of product

Offers

How can you pull lightweight product offers, including a warehouse inventory breakdown?

The Offers endpoint returns the current inventory and pricing per product, allowing field filtering and optional warehouse-level inventory breakdowns.

GET {{api-host}}/retailers/{{retailer-id}}/offers?service_type=ecommerce&limit=200&offset=0 (read more)

View ExampleMore

View Example – MulticurrencyMore

If enabled for your retailer account, the response will include pricing in multiple currencies.

Request:

GET /retailers/3/offers?service_type=ecommerce&limit=200&offset=0&warehouses=true

Response:

[
  {
    "id": 90809,
    "sku": "32291-06537-10",
    "upc": "888731282960",
    "ean": null,
    "retailer_sku": "512341-2443",
    "currency": "USD",
    "supplier_id": 1,
    "supplier_name": "Melissa",
    "model": "32291-06537",
    "title": "BEACH SLIDE SHINE",
    "retail_price": 850000,
    "prices": {
      "USD": [
        {
          "type": "retail",
          "value": 850000,
          "currency": "USD",
          "retailer_id": 9948,
          "start_date": "2024-01-15T11:41:59.173Z",
          "is_active": true,
          "creation_date": "2024-01-15T11:41:58.173Z",
        },
        {
          "type": "sale",
          "value": 799999,
          "currency": "USD",
          "retailer_id": 9948,
          "start_date": "2024-01-15T11:41:59.173Z",
          "is_active": true,
          "creation_date": "2024-01-15T11:41:58.173Z",
        },
      ],
      "EUR": [
        {
          "type": "retail",
          "value": 820000,
          "currency": "EUR",
          "retailer_id": 9948,
          "start_date": "2024-01-15T11:41:59.173Z",
          "is_active": true,
          "creation_date": "2024-01-15T11:41:58.173Z",
        },
        {
          "type": "sale",
          "value": 759999,
          "currency": "EUR",
          "retailer_id": 9948,
          "start_date": "2024-01-15T11:41:59.173Z",
          "is_active": true,
          "creation_date": "2024-01-15T11:41:58.173Z",
        },
      ],
    },
    "special_sale_price": null,
    "special_sale_price_start": null,
    "special_sale_price_end": null,
    "available_inventory": 120,
    "warehouses": [
      {
        "warehouse_name": "East Coast Fulfillment Center",
        "warehouse_id": "WH-1234",
        "available_inventory": 80
      },
      {
        "warehouse_name": "West Coast Fulfillment Center",
        "warehouse_id": "WH-5678",
        "available_inventory": 40
      }
    ]
  }
]

Response ParametersMore

Name		Type	Sample	Description
id		number	90809	Cymbio’s unique offer identifier
sku		string	32291-06537-10	Product SKU
upc		string	888731282960	Product UPC
ean		string	null	Product EAN
retailer_sku		string	512341-2443	Product’s SKU on the retailer platform
currency		string	USD	Main Currency
supplier_id		number	1	Cymbio’s unique brand/vendor identifier
supplier_name		string	Melissa	Name of the brand/vendor
model		string	32291-06537	Parent SKU/Style
title		string	BEACH SLIDE	Product title
retail_price		number	850000	Retail price in cents
special_sale_price		number	null	Sale price in cents
special_sale_price_start		number	null	Sale price start date
special_sale_price_end		number	null	Sale price end date
available_inventory		number	120	Total inventory available across all warehouses
warehouses		object[]		List of warehouse-level inventory (only returned if enabled). This parameter is disabled by default (false)
	warehouse_name	string	East Coast Fulfillment Center	Warehouse name
	warehouse_id	number	1234	Cymbio’s unique warehouse identifier
	available_inventory	number	80	Inventory available in a specific warehouse

Orders

How can you create an order and get the order status?

Create Order

Pushing Orders for Fulfillment

POST {{api-host}}/v3/retailers/{{retailer-id}}/orders (read more)

NOTE: Either send a list of your codes or utilize Cymbio’s shipping method codes.

View ExampleMore

Request ParametersMore

Name		Mandatory?	Type	Sample	Description
billing_address		Optional	object		Describes all the billing information
	address1	Optional	string	42606 Christy St.	Billing Address 1
	address2	Optional	string		Billing Address 2
	city	Optional	string	Fremont	Billing City
	company_name	Optional	string	IFCHIC	Billing Company Name
	country	Optional	string	US	Billing Country (ISO 3166-2)
	email	Optional	string	merch@ifchic.com	Billing Email
	first_name	Optional	string	Davis	Billing First Name
	last_name	Optional	string	Huang	Billing Last Name
	phone_number	Optional	string	5105731556	Billing Phone Number
	state	Optional	string	CA	Billing State (ISO 3166-2)
	zip_code	Optional	string	94538	Billing Zip Code
shipping_address		Mandatory	object		Describes all the shipping information
	address1	Mandatory	string	42606 Christy St.	Shipping Address 1
	address2	Optional	string		Shipping Address 2
	city	Mandatory	string	Fremont	Shipping City
	company_name	Optional	string	IFCHIC	Shipping Company Name
	country	Mandatory	string	US	Shipping Country Code (ISO 3166-2)
	email	Optional	string	merch@ifchic.com	Shipping Email Address
	first_name	Optional	string	Davis	Shipping First Name
	last_name	Optional	string	Huang	Shipping Last Name
	phone_number	Optional	string	5105731556	Shipping Phone Number
	state	Mandatory	string	CA	Shipping State (ISO 3166-2)
	zip_code	Mandatory	string	94538	Shipping Zip Code
order_lines			object[]
	quantity	Mandatory	number	1	Number of units
	sku	Custom	string	1950401	Variant’s SKU
	upc	Custom	string	123456789012	Variant’s UPC
	ean	Custom	string	1234567890123	Variant’s EAN
	id_in_source	Optional	string	1_A	Retailer/Marketplace line order identifier
	billed_amount	Optional	number	10000	Amount paid by the end customer on the website per unit sold in cents (after discount without taxes) in the currency the customer paid
	box_type	Optional	string	carton_1	Used in cases the marketplace supplies the boxes and wants to declare which box to use
	discount_amount	Optional	number	1000	Amount in cents of discounts at the order line level
	commission_fee	Optional	number	1500	Amount in cents of the commission of the marketplace at the order line level
	unit_price	Optional	number	5000	For dropship cases, to indicate the price in cents the retailer expects to be billed by the brand per unit, without tax or shipping
	tax_billed_amount	Optional	number	1200	The tax per line in cents the end-customer paid for all units on this line
	customization	Optional	object		Used for products that support personalization like engravings
	discount_label	Optional	string	Christmas_2023	The name of the promotion campaign
	expected_delivery_date	Optional	date
retailer_order_id		Mandatory	string	2310ULTNQ	PO Number
shipping_method_code		Mandatory	string	UPS_GND	Shipping Method Code (See below a complete list)
shipping_paid		Optional	number	0	The Shipping Cost paid by the end customer in cents without tax after discount
shipping_tax		Optional	number		Shipping taxes in cents
shipping_duties		Optional	number		Duties on shipping in case of cross-border shipments in cents
shipping_discount		Optional	number		Discount on Shipping in cents
duties_tax		Optional	number		Duties on products in case of cross-border shipments in cents
sales_division_code		Optional	string		Used in cases the retailer/marketplace is operating multiple websites, either a code or the name of the website
sales_order_number		Optional	string		The unique identifier of the order that is visible for the end-customer if different from the retailer_order_id
is_gift		Mandatory	boolean		Should wrap as a gift
gift_message		Optional	string		A Gift Message
currency		Optional	string	USD	The currency used in the order. defaults to USD
ship_until		Optional	date		If order isn’t shipped by this date, the retailer/marketplace expect the brand to cancel this order
warehouse_id		Optional	number		In cases the retailer/marketplace orchestrates the orders fulfillment and the brand has multiple warehouses. To use this feature there is a need to coordinate with Cymbio’s Ops team prior

Order Cancellation

Pushing Orders Cancellations

POST {{api-host}}/v3/retailers/{{retailer-id}}/orders/{{order-id}}/cancel (read more)

View ExampleMore

Order Statuses

Pulling Order Statuses (order line level):

GET {{api-host}}/v3/retailers/{{retailer-id}}/orders/order-line?cymbio_order_id={{order-id}} (read more)

Order StatusMore

Order Line Status	Description
Rejected before acceptance	Order lines that were rejected by Cymbio due to inventory or rules upon order capturing
In progress	Order lines that are currently of being fulfilled
Partially shipped	Order lines where part or quantity of the line was shipped and part was canceled
Shipped	Order lines that were shipped
Rejected by warehouse	Order lines that were canceled

View ExampleMore

Request:

GET /v3/retailers/3/orders/order-line?cymbio_order_id=7590

Response:

{
    "cymbioOrderId": 7590,
    "orderPo": "asd123",
    "salesOrderNumber": null,
    "orderIdInSource": null,
    "createdAt": "2022-01-11T08:11:42.258Z",
    "orderLines": [
        {
            "quantity": 1,
            "id_in_source": null,
            "status": "Shipped",
            "shipments": [
                {
                    "quantity": 1,
                    "trackingNumber": "77777777",
                    "shippingCarrier": "ups"
                }
            ],
            "variant": {
                "sku": "AIREZ0721-BLACK-M/L",
                "model": "AIREZ0721_BLACK",
                "title": "Cosabella Aire Hotpant | BLACK",
                "upc": "887981308420",
                "ean": null
            }
        },
        {
            "quantity": 1,
            "id_in_source": null,
            "status": "Rejected by warehouse",
            "rejections": [
                {
                    "quantity": 1
                }
            ],
            "variant": {
                "sku": "AIREZ0721-BLACK-S/M",
                "model": "AIREZ0721_BLACK",
                "title": "Cosabella Aire Hotpant | BLACK",
                "upc": "887981308413",
                "ean": null
            }
        },
        {
            "quantity": 4,
            "id_in_source": null,
            "status": "Shipped",
            "shipments": [
                {
                    "quantity": 4,
                    "trackingNumber": "888888888",
                    "shippingCarrier": "ups"
                }
            ],
            "variant": {
                "sku": "20S1DR51LM-BLK-0",
                "model": "20S1DR51LM-BLK",
                "title": "Ariel Lame Mini Wrap Dress",
                "upc": "728870106720",
                "ean": null
            }
        },
        {
            "quantity": 3,
            "id_in_source": null,
            "status": "Partially shipped",
            "shipments": [
                {
                    "quantity": 1,
                    "trackingNumber": "888888888",
                    "shippingCarrier": "ups"
                }
            ],
            "rejections": [
                {
                    "quantity": 2
                }
            ],
            "variant": {
                "sku": "20S1DR51LM-BLK-2",
                "model": "20S1DR51LM-BLK",
                "title": "Ariel Lame Mini Wrap Dress",
                "upc": "728870106713",
                "ean": null
            }
        }
    ]
}

NOTE: We suggest pulling order status on an hourly basis.

RLR (Reverse Logistics Return)

How can you create an RLR Notifications?

Create RLR Notifications

Cymbio provides the ability for retailers to create the return requests information about returns on the way back to the brand warehouse.

Create the Reverse Logistics Return (RLR) API:

POST {{api-host}}/v3/retailers/{{retailer-id}}/reverse-logistics-returns (read more)

View ExampleMore

Request ParametersMore

Name		Mandatory?	Type	Sample	Description
retailer_order_id		Mandatory	string	2310ULTNQ	PO Number
id_in_source		Optional	string	1878324	Retailer/Marketplace order identifier
reason_type		Mandatory	Selected from Reason Types	item_damaged	Reason type for returning the goods
reason_text		Optional	string	Item was damaged in delivery	Additional information
tracking_number		Optional	string	1z047362784362	The tracking number used to return the goods
line_items		Mandatory	object[]
	upc	Custom	string	123456789012	Variant’s UPC
	ean	Custom	string	1234567890123	Variant’s EAN
	amount	Mandatory	number	1	Number of units
	tracking_number	Optional	string	1z047362784362	The tracking number used to return the goods
	id_in_source	Optional	string	1_A	Retailer/Marketplace line order identifier
	reason_type	Optional	Selected from Reason Types	item_damaged	Reason type for returning the goods
	reason_text	Optional	string	Item was damaged in delivery	Additional information

Reason Types

Available reason types for RLR notifications:

unknown
not_receipt
wrong_item
item_damaged
different_description
mutual_agree
change_mind
item_missing
expectation_failed
item_fake
physical_damage
functional_damage
other

Returns

How can you fetch the returns that have been processed by the brand?

Get Returns

GET {{api-host}}/v3/retailers/{{retailer-id}}/returns?filter={"status":"not_acknowledged"} (read more)

NOTE: We expect you to acknowledge each return ID you receive.

Response ValuesMore

Name			Mandatory?	Type	Sample	Description
returnId			Mandatory	number	1772	Cymbio Internal Return ID
salesOrderNumber			Optional	string	kering-872023-005	End-Customer Order ID
cymbioOrderId			Optional	number	39617	Cymbio Internal Order ID
orderIdInSource			Optional	string	null	Not relevant for API users
orderPo			Mandatory	string	kering-872023-005-A	Retailer Order ID and/or PO#
reasonCode			Optional	string	other	Return Reason Code
reason			Optional	string	null	Return Reason Text
acknowledged			Optional	boolean	false	Acknowledgment status
createdAt			Optional	date	2023-09-21T06:40:17.932Z	Return Created at Date
updatedAt			Optional	date	2023-11-08T13:42:05.912Z	Return Updated at Date
returnLines			Mandatory	object
	identifiers		Mandatory	object
		sku	Mandatory	string	805693581	Variant SKU
		upc	Mandatory	string	3615090040163	Variant UPC
	orderedQuantity		Mandatory	number	1	The original ordered quantity
	returnedQuantity		Mandatory	number	1	The returned quantity

View ExampleMore

Acknowledge Return

PUT {{api-host}}/v3/retailers/{{retailer-id}}/return/{{return-id}}/acknowledge (read more)

View ExampleMore

API

Integrate with Cymbio via API

Get Started

Authentication

Authentication Parameters

Access Scopes

Products/Inventory

Offers

Orders

Create Order

Order Cancellation

Order Statuses

RLR (Reverse Logistics Return)

Create RLR Notifications

Reason Types

Returns

Get Returns

Acknowledge Return

Recent Blog Posts

The Agentic Commerce Pioneers: A&F and Fabletics

PayPal to Acquire Cymbio, Accelerating Agentic Commerce Capabilities

The $5 Trillion Wake-Up Call That Brands Cannot Ignore

API

Integrate with Cymbio via API

Get Started

Authentication

Authentication Parameters

Access Scopes

Products/Inventory

Offers

Orders

Create Order

Order Cancellation

Order Statuses

RLR (Reverse Logistics Return)

Create RLR Notifications

Reason Types

Returns

Get Returns

Acknowledge Return

Recent Blog Posts

The Agentic Commerce Pioneers: A&F and Fabletics

PayPal to Acquire Cymbio, Accelerating Agentic Commerce Capabilities

The $5 Trillion Wake-Up Call That Brands Cannot Ignore

You’re Almost Done!

You’re Almost Done!