Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
email: partner-api@wish.com
x-wish-dev-contact:
assignee: kwei
email: marketplace-external-api@contextlogic.com
description: 'Wish Marketplace V3 API
# General Information
The Wish Marketplace API will be using oAuth to authenticate in order to offer better security for its users
* Learn about oAuth here.'
version: 3.0.65
title: Wish Marketplace V3 Variations API
servers:
- url: https://merchant.wish.com
description: V3 API endpoint
security:
- OAuth2: []
tags:
- description: Variations APIs
name: Variations
paths:
/api/v3/products/{id}/variations:
post:
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Variation'
description: successfully created a variation
'400':
content:
application/json:
examples:
InvalidParameter:
value:
message: There is an existing variation with such SKU.
code: '90001'
schema:
$ref: '#/components/schemas/APIError'
description: failed to add a variation
parameters:
- required: true
in: path
description: ID of the product to add a variation to
name: id
schema:
type: string
format: object-id
tags:
- Variations
summary: Create a variation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddVariation'
security:
- OAuth2:
- products:write
operationId: createVariation
x-code-samples:
- lang: python_requests
source: "import requests\n\nurl = \"https://merchant.wish.com/api/v3/products/{id}/variations\"\n\npayload = \"{\\\"attributes\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":[\\\"string\\\"]}],\\\"cost\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"gtin\\\":\\\"string\\\",\\\"image\\\":\\\"http://example.com\\\",\\\"inventories\\\":[{\\\"inventory\\\":0,\\\"warehouse_id\\\":\\\"string\\\"}],\\\"logistics_details\\\":{\\\"customs_declared_name\\\":\\\"string\\\",\\\"customs_declared_value\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"customs_hs_code\\\":\\\"string\\\",\\\"declared_local_name\\\":\\\"string\\\",\\\"declared_name\\\":\\\"string\\\",\\\"height\\\":0,\\\"length\\\":0,\\\"origin_country\\\":\\\"string\\\",\\\"pieces\\\":0,\\\"restricted_flags\\\":[\\\"HAS_POWDER\\\"],\\\"weight\\\":0,\\\"width\\\":0},\\\"merchant_set_cost\\\":0,\\\"options\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":\\\"string\\\"}],\\\"price\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"quantity_value\\\":0,\\\"sku\\\":\\\"string\\\"}\"\nheaders = {\n 'content-type': \"application/json\",\n 'authorization': \"Bearer REPLACE_BEARER_TOKEN\"\n }\n\nresponse = requests.request(\"POST\", url, data=payload, headers=headers)\n\nprint(response.text)"
- lang: java_unirest
source: "HttpResponse<String> response = Unirest.post(\"https://merchant.wish.com/api/v3/products/{id}/variations\")\n .header(\"content-type\", \"application/json\")\n .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n .body(\"{\\\"attributes\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":[\\\"string\\\"]}],\\\"cost\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"gtin\\\":\\\"string\\\",\\\"image\\\":\\\"http://example.com\\\",\\\"inventories\\\":[{\\\"inventory\\\":0,\\\"warehouse_id\\\":\\\"string\\\"}],\\\"logistics_details\\\":{\\\"customs_declared_name\\\":\\\"string\\\",\\\"customs_declared_value\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"customs_hs_code\\\":\\\"string\\\",\\\"declared_local_name\\\":\\\"string\\\",\\\"declared_name\\\":\\\"string\\\",\\\"height\\\":0,\\\"length\\\":0,\\\"origin_country\\\":\\\"string\\\",\\\"pieces\\\":0,\\\"restricted_flags\\\":[\\\"HAS_POWDER\\\"],\\\"weight\\\":0,\\\"width\\\":0},\\\"merchant_set_cost\\\":0,\\\"options\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":\\\"string\\\"}],\\\"price\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"quantity_value\\\":0,\\\"sku\\\":\\\"string\\\"}\")\n .asString();"
- lang: php_curl
source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n CURLOPT_URL => \"https://merchant.wish.com/api/v3/products/{id}/variations\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => \"{\\\"attributes\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":[\\\"string\\\"]}],\\\"cost\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"gtin\\\":\\\"string\\\",\\\"image\\\":\\\"http://example.com\\\",\\\"inventories\\\":[{\\\"inventory\\\":0,\\\"warehouse_id\\\":\\\"string\\\"}],\\\"logistics_details\\\":{\\\"customs_declared_name\\\":\\\"string\\\",\\\"customs_declared_value\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"customs_hs_code\\\":\\\"string\\\",\\\"declared_local_name\\\":\\\"string\\\",\\\"declared_name\\\":\\\"string\\\",\\\"height\\\":0,\\\"length\\\":0,\\\"origin_country\\\":\\\"string\\\",\\\"pieces\\\":0,\\\"restricted_flags\\\":[\\\"HAS_POWDER\\\"],\\\"weight\\\":0,\\\"width\\\":0},\\\"merchant_set_cost\\\":0,\\\"options\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":\\\"string\\\"}],\\\"price\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"quantity_value\\\":0,\\\"sku\\\":\\\"string\\\"}\",\n CURLOPT_HTTPHEADER => array(\n \"authorization: Bearer REPLACE_BEARER_TOKEN\",\n \"content-type: application/json\"\n ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}"
- lang: javascript_jquery
source: "var settings = {\n \"async\": true,\n \"crossDomain\": true,\n \"url\": \"https://merchant.wish.com/api/v3/products/{id}/variations\",\n \"method\": \"POST\",\n \"headers\": {\n \"content-type\": \"application/json\",\n \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n },\n \"processData\": false,\n \"data\": \"{\\\"attributes\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":[\\\"string\\\"]}],\\\"cost\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"gtin\\\":\\\"string\\\",\\\"image\\\":\\\"http://example.com\\\",\\\"inventories\\\":[{\\\"inventory\\\":0,\\\"warehouse_id\\\":\\\"string\\\"}],\\\"logistics_details\\\":{\\\"customs_declared_name\\\":\\\"string\\\",\\\"customs_declared_value\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"customs_hs_code\\\":\\\"string\\\",\\\"declared_local_name\\\":\\\"string\\\",\\\"declared_name\\\":\\\"string\\\",\\\"height\\\":0,\\\"length\\\":0,\\\"origin_country\\\":\\\"string\\\",\\\"pieces\\\":0,\\\"restricted_flags\\\":[\\\"HAS_POWDER\\\"],\\\"weight\\\":0,\\\"width\\\":0},\\\"merchant_set_cost\\\":0,\\\"options\\\":[{\\\"name\\\":\\\"string\\\",\\\"value\\\":\\\"string\\\"}],\\\"price\\\":{\\\"amount\\\":0,\\\"currency_code\\\":\\\"USD\\\"},\\\"quantity_value\\\":0,\\\"sku\\\":\\\"string\\\"}\"\n}\n\n$.ajax(settings).done(function (response) {\n console.log(response);\n});"
- lang: shell_curl
source: "curl --request POST \\\n --url 'https://merchant.wish.com/api/v3/products/{id}/variations' \\\n --header 'authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"attributes\":[{\"name\":\"string\",\"value\":[\"string\"]}],\"cost\":{\"amount\":0,\"currency_code\":\"USD\"},\"gtin\":\"string\",\"image\":\"http://example.com\",\"inventories\":[{\"inventory\":0,\"warehouse_id\":\"string\"}],\"logistics_details\":{\"customs_declared_name\":\"string\",\"customs_declared_value\":{\"amount\":0,\"currency_code\":\"USD\"},\"customs_hs_code\":\"string\",\"declared_local_name\":\"string\",\"declared_name\":\"string\",\"height\":0,\"length\":0,\"origin_country\":\"string\",\"pieces\":0,\"restricted_flags\":[\"HAS_POWDER\"],\"weight\":0,\"width\":0},\"merchant_set_cost\":0,\"options\":[{\"name\":\"string\",\"value\":\"string\"}],\"price\":{\"amount\":0,\"currency_code\":\"USD\"},\"quantity_value\":0,\"sku\":\"string\"}'"
/api/v3/products/variations/colors:
get:
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ColorList'
description: successfully queried for colors
parameters:
- required: false
in: query
description: The beginning id (inclusive) of the color result array. The lexicographically smallest id will be used if not provided.
name: id_min
schema:
type: string
- required: false
in: query
description: The ending id (inclusive) of the color result array. The lexicographically largest id will be used if not provided.
name: id_max
schema:
type: string
- required: false
in: query
description: The attribute to sort colors in the response.
name: sort_by
schema:
default: id.asc
pattern: ^id(\.(asc|desc))?$
type: string
- required: false
in: query
description: The maximum number of records in the response. All records will be returned by default.
name: limit
schema:
minimum: 1
type: integer
tags:
- Variations
summary: Get a list of accepted colors
security:
- OAuth2: []
operationId: getColors
x-code-samples:
- lang: python_requests
source: 'import requests
url = "https://merchant.wish.com/api/v3/products/variations/colors"
querystring = {"id_min":"SOME_STRING_VALUE","id_max":"SOME_STRING_VALUE","sort_by":"SOME_STRING_VALUE","limit":"SOME_INTEGER_VALUE"}
headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}
response = requests.request("GET", url, headers=headers, params=querystring)
print(response.text)'
- lang: java_unirest
source: "HttpResponse<String> response = Unirest.get(\"https://merchant.wish.com/api/v3/products/variations/colors?id_min=SOME_STRING_VALUE&id_max=SOME_STRING_VALUE&sort_by=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE\")\n .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n .asString();"
- lang: php_curl
source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n CURLOPT_URL => \"https://merchant.wish.com/api/v3/products/variations/colors?id_min=SOME_STRING_VALUE&id_max=SOME_STRING_VALUE&sort_by=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => array(\n \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}"
- lang: javascript_jquery
source: "var settings = {\n \"async\": true,\n \"crossDomain\": true,\n \"url\": \"https://merchant.wish.com/api/v3/products/variations/colors?id_min=SOME_STRING_VALUE&id_max=SOME_STRING_VALUE&sort_by=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE\",\n \"method\": \"GET\",\n \"headers\": {\n \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n }\n}\n\n$.ajax(settings).done(function (response) {\n console.log(response);\n});"
- lang: shell_curl
source: "curl --request GET \\\n --url 'https://merchant.wish.com/api/v3/products/variations/colors?id_min=SOME_STRING_VALUE&id_max=SOME_STRING_VALUE&sort_by=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
description: The list of accepted colors.
components:
schemas:
WarehouseInventory:
required:
- warehouse_id
- inventory
type: object
properties:
inventory:
minimum: 0
type: integer
description: The inventory of a variation in the warehouse.
maximum: 500000
warehouse_id:
type: string
description: The ID of the warehouse.
format: object-id
Price:
required:
- amount
- currency_code
type: object
properties:
amount:
minimum: 0
type: number
description: Non-negative amount in decimals.
format: float
currency_code:
format: iso-4217
type: string
description: The 3-letter currency code defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).
example: USD
ColorList:
items:
$ref: '#/components/schemas/ColorInfo'
type: array
description: The list of accepted colors.
Variation:
type: object
allOf:
- $ref: '#/components/schemas/ProductVariation'
- type: object
VariationAttribute:
required:
- name
type: object
properties:
name:
type: string
description: The name of the attribute. Input the relevant "name". Please browse our [Taxonomy APIs](/documentation/api/v3/reference#operation/getCategoryAttributes) for possible attribute names.
value:
items:
type: string
type:
- array
- 'null'
description: The value of the attribute. Can be set to null to remove the attribute. Input the relevant "accepted_values". Please browse our [Taxonomy APIs](/documentation/api/v3/reference#operation/getCategoryAttributes) for possible attribute values.
AttributeResponse:
required:
- name
type: object
properties:
name:
type: string
description: The name of the attribute.
value:
items:
type: string
type:
- array
- 'null'
description: The value of the attribute.
Option:
required:
- name
- value
type: object
properties:
name:
type: string
description: The name of the option like SIZE and COLOR.
value:
minLength: 1
type: string
description: The value of the option.
LogisticsInfo:
type: object
properties:
customs_declared_name:
type: string
description: Declared name of the product used for customs clearance. This is often displayed on the product packaging.
origin_country:
type: string
description: Country where the product is manufactured, produced, or grown. Country code should follow [ISO 3166 Alpha-2 code](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en). This is a required field when creating a new product listing (Create a Product) or creating a new variation (Create a variation).
format: iso-3166
weight:
type: number
description: The weight of the package in which your product will ship to the customer (units in grams).</br> This is a required field for mainland China-based merchants when creating a new product listing (Create a Product) or adding variations to existing product listings (Create a variation).
format: float
restricted_flags:
items:
enum:
- HAS_POWDER
- HAS_LIQUID
- HAS_BATTERY
- HAS_METAL
type: string
type:
- array
- 'null'
description: Whether the product contains certain items or materials.</br> __Battery__ - Products that contain batteries, either replaceable or built into the product.</br> __Liquid__ - Products that consist of a substance that has a consistency like water or oil, including semi-liquids such as creams, gels, lubes, etc.</br> __Metal__ - Products made of or containing metal as a material component.</br> __Powder__ - Any product that is composed of fine, dry particles.
customs_hs_code:
type: string
description: Harmonization System Code for customs declaration.
height:
type: number
description: The height of the package in which your product will ship to the customer (units in cm).
format: float
width:
type: number
description: The width of the package in which your product will ship to the customer (units in cm).
format: float
length:
type: number
description: The length of the package in which your product will ship to the customer (units in cm).
format: float
declared_name:
type: string
description: The product name for customs declaration.</br> `This field will be deprecated soon and replaced with customs_declared_name.`
customs_declared_value:
type: object
description: The price of the product for customs declaration.
allOf:
- $ref: '#/components/schemas/Price'
pieces:
type: integer
description: The number of pieces associated with the variation.
declared_local_name:
type: string
description: The product name in local language for customs declaration.
EditableVariationParams:
type: object
properties:
sku:
minLength: 1
type: string
description: The Stock Keeping Unit of the variation.
maxLength: 80
quantity_value:
minimum: 0
type:
- number
- 'null'
description: The total quantity of the product variant (in the given unit) that is used to calculate price per unit. Note that if a product has multiple product variants, you will need to set quantity values for each product variant. [Learn More](https://merchantfaq.wish.com/hc/en-us/articles/4405383750555).
format: float
image:
type: string
description: The URL of the image associated with the variation. This is a required field when adding a new product listing with variations (Create a Product) or adding variations to existing product listings (Create a variation). The variation images don’t need to be unique (multiple variations can have the same image), but they have to be specified for each variation. These images must be a part of extra_images.
format: uri
price:
type: object
description: The price of the variation. Price is required for rev-share merhcants.
allOf:
- $ref: '#/components/schemas/Price'
merchant_set_cost:
minimum: 0
type:
- number
- 'null'
description: Supply cost maintained by merchants on variation level
format: float
cost:
type: object
description: The cost of the variation. Cost is required for cost-based merchants.
allOf:
- $ref: '#/components/schemas/Price'
gtin:
pattern: ^[0-9]{8,14}$
type:
- string
- 'null'
description: Should be 8 to 14 digits GTIN (UPC, EAN, ISBN) that contains no letters or other characters. This number is barcode symbology used for tracking trade items in stores and scanning them at the point of sale.
attributes:
items:
$ref: '#/components/schemas/VariationAttribute'
type:
- array
- 'null'
description: The custom attributes of the variation. Merchants may use the "name" and "value" fields here to add specific attributes for the product’s category. Our [Taxonomy APIs](/documentation/api/v3/reference#operation/getCategoryAttributes) contains the list of all attributes for each category, mentions which ones are required, and the corresponding accepted values for each attribute.
inventories:
items:
$ref: '#/components/schemas/WarehouseInventory'
type: array
description: The inventory of the variation in each warehouse.
options:
items:
$ref: '#/components/schemas/Option'
type: array
description: This field is used to define the parameters for the creation of variations. You can create your variations with traditional Color and Size fields or use category-specific attributes. Each combination of option values may be a variation for that product. See which category-specific attributes can be used by using the [Taxonomy APIs](/documentation/api/v3/reference#operation/getCategoryAttributes) and the field attributes.constraint.is_variation_attribute.
logistics_details:
type: object
description: The logistics details of the variation.
allOf:
- $ref: '#/components/schemas/LogisticsInfo'
ProductVariation:
type: object
properties:
sku:
minLength: 1
type: string
description: The Stock Keeping Unit of the variation.
status:
enum:
- ENABLED
- DISABLED
- REMOVED_BY_WISH
type: string
description: The status of the variation. Removed variations cannot be updated.
quantity_value:
minimum: 0
type: number
description: The total quantity of the product variant (in the given unit) that is used to calculate price per unit. Note that if a product has multiple product variants, you will need to set quantity values for each product variant. [Learn More](https://merchantfaq.wish.com/hc/en-us/articles/4405383750555).
format: float
product_id:
readOnly: true
type: string
description: The ID of the product.
format: object-id
image:
type: string
description: The URL of the image associated with the variation.
format: uri
options:
items:
$ref: '#/components/schemas/Option'
type: array
description: Parameters used to define the variations. Each combination of option values may be a variation for that product.
price:
type: object
description: The price of the variation.
allOf:
- $ref: '#/components/schemas/Price'
cost:
type: object
description: The cost of the variation.
allOf:
- $ref: '#/components/schemas/Price'
gtin:
type: string
description: The Global Trade Item Number of the product.
request_id:
readOnly: true
type: string
description: Identifier for the variation create request. Can be used with the [Get Product Create or Update Request endpoint](/documentation/api/v3/reference#operation/getProductUpdateRequest) to track the status of the request during the Automated Listing Review process.
attributes:
items:
$ref: '#/components/schemas/AttributeResponse'
type:
- array
- 'null'
description: The custom attributes of the variation.
inventories:
items:
$ref: '#/components/schemas/WarehouseInventory'
type: array
description: The inventory of the variation in each warehouse.
id:
readOnly: true
type: string
description: The ID of the variation.
format: object-id
logistics_details:
type: object
description: The logistics details of the variation.
allOf:
- $ref: '#/components/schemas/LogisticsInfo'
APIError:
required:
- code
- message
type: object
properties:
message:
type: string
code:
type: integer
format: int32
AddVariation:
type: object
allOf:
- $ref: '#/components/schemas/EditableVariationParams'
- required:
- sku
- inventories
- price
type: object
ColorInfo:
required:
- name
- id
type: object
properties:
id:
type: string
description: 'The ID of the color. E.g. antiquegold. C olor IDs are subject to change. '
name:
type: string
description: The display name of the color. E.g. Antique Gold.
securitySchemes:
OpenID:
type: openIdConnect
openIdConnectUrl: https://merchant.wish.com/oidc/.well-known/openid-configuration
OAuth2:
type: oauth2
flows:
authorizationCode:
scopes:
payments:write: Update payments
tickets:write: Write customer tickets
epc:read: read EPC info
returns:write: Write returns
returns:read: Read returns
fbw:read: Read FBW
products:read: Read products
payments:read: Read payments
fbw:write: Write FBW
merchant:write: Write merchant
products:write: Write products
ratings:read: Read ratings
videos:read: Read videos
compliance:write: Write Compliance
product_boost:read: Read ProductBoost
listing_quality:read: Read listing quality
webhook:write: Write webhook
orders:read: Read orders
compliance:read: Read Compliance
fbs:read: Read FBS
penalties:read: Read penalties
penalties:write: Update penalties
infractions:read: Read infractions
orders:write: Update orders
merchant:read: Read merchant
notifications:write: Write notifications
announcements:read: Read announcements
product_boost:write: Write ProductBoost
notifications:read: Read notifications
webhook:read: Read webhook
qoo10:read: Read Qoo10
wps_parcel:write: Write WishParcel
wps_parcel:read: Read WishParcel
tickets:read: Read customer tickets
infractions:write: Write infractions
videos:write: Write videos
epc:write: write EPC info
tokenUrl: https://merchant.wish.com/api/v3/oauth/access_token
refreshUrl: https://merchant.wish.com/api/v3/oauth/refresh_token
authorizationUrl: https://merchant.wish.com/v3/oauth/authorize
externalDocs:
url: https://merchant.wish.com/documentation/api/v3/explorer
description: API explorer
x-wish-hidden: false