API Documentation
Getting Started
The Proven Winners API is currently in limited partner release. We depend on
feedback about what works and what needs work, so you are encouraged to contact
the developers.
API keys can be obtained from a site admin or developer, for now. Users may ultimately
be able to manage their own keys.
The API generally assumes that the holder of an API key is the user that the key is connected
to - so under normal circumstances, only use the API server-side, and never expose your API key
where someone else can see it.
API URL
https://www.provenwinners.com/api/v0/
All API URLs listed in this documentation are relative to the above URL.
For example, the plant search endpoint is plant/search so the endpoint URL will be
https://www.provenwinners.com/api/v0/plant/search
RESTful
Requests should be made with HTTP GET or POST.
Succcessful requests return a status code of 200 .
Failed requests return a 404 or 403 status code as well as a description in the body of the response.
All response data is delivered as JSON in the response body.
Regardless of success or failure, the response content type is always application/json.
Request Format
Request parameters can be passed either in querystring or in the request body.
Parameters passed in the request body should be formatted
as JSON and the content type should be set to application/json.
It is preferred that JSON request body is used rather than querystring.
Future releases of the API may require JSON requests.
When passing parameters in the query string, pass array data types as a comma-separated
list contained within square brackets like so: param=[a,b,c]. JSON requests may simply use JSON arrays.
Regardless of format or endpoint, all requests MUST pass a valid API key as a parameter
called 'apikey'. API keys can be obtained from a site admin or developer, for now.
Users may ultimately be able to manage their own keys.
Endpoints
ping Provides a simple endpoint for checking availability and authorization.
URL
https://www.provenwinners.com/api/v0/ping
plant/search Get plants, using general or specific parameters. Parameters combine in logical AND. To look up a particular plant, just provide a single NID or plant ID.
URL
https://www.provenwinners.com/api/v0/plant/search
Parameters
Name Type Description
changed_after unix timestamp | YYYY-MM-DD Anything changed after this date will be returned. introduction_year YYYY Retail introduction year (match). introduction_year_before YYYY Anything introduced to retail stores on or before this year will be returned. professional_release_before unix timestamp Anything released before this date will be returned. professional_release_after unix timestamp Anything released after this date will be returned. public_release_before unix timestamp Anything released before this date will be returned. public_release_after unix timestamp Anything released after this date will be returned. member_assignment array Member secret keys. Provide multiple keys to get only plants that are assigned to all specified members (as opposed to plants that are assigned to at least one specified member). Note that member assignment is never exposed in returned data. programs array Program names. Case sensitive. This field is exposed in the identity response section, though that section need not be requested in the response. Provide multiple program names to get only plants that are assigned to all specified programs. Provide a partial name to match all programs containing the string. genus string Name. Case sensitive. species string Name. Case sensitive. series string Name. Case sensitive. variety string Name. Case sensitive. variety_starts_with string Name. Case sensitive. common_name string Name. Case sensitive. plantid array Plant IDs nid array NIDs sections array Array of optional sections to include with each plant: images, awards, series, culture, features, identity, characteristics, needs. limit integer Results per page. Defaults to 1000. page integer Result page. Defaults to 1.
Response Data
Name Type
nid integer plantid integer title string changed timestamp created timestamp url string / URL visibility object: refer to section definition images object: refer to section definition awards Array of award objects. Each object has "year", "title" and "location" series object: refer to section definition culture A basic plant culture object, see default culture/search object structure features object: refer to section definition identity object: refer to section definition characteristics object: refer to section definition needs object: refer to section definition
Response section: visibility
Name Type
published boolean workflow_status string introduction_year string (YYYY) professional_release_date string (YYYY-MM-DD) public_release_date string (YYYY-MM-DD)
Response section: images
Name Type
featured Object containing image nid (unique identifier), type ("Tag Image", "Close-up", etc) and sizes. Sizes is an object of URLs (keys: "1024","500-sq"). all Array of objects in same format as "featured"
Response section: series
Name Type
title string plants Array of objects that identify plants in the series (keys: "nid", "plantid")
Response section: features
Name Type
adaptable_as_houseplant boolean award_winner boolean bog_plant boolean continuous_bloom_rebloom boolean is_disease_resistant boolean erosion_control boolean is_edible boolean fragrant_flower boolean long_blooming boolean fall_interest boolean foliage_interest boolean winter_interest boolean small_or_miniature boolean fun_facts string / HTML fragrant_foliage boolean heat_tolerant boolean deadheading_not_necessary boolean drought_tolerant boolean salt_tolerant boolean is_succulent boolean water_plant boolean vine boolean grass boolean native_to_north_america boolean description string fun_statement string features string / HTML attracts_wildlife array of strings. Only applicable wildlife are listed. resists_wildlife array of strings. Only applicable wildlife are listed. harmful_to_wildlife array of strings. Only applicable wildlife are listed.
Response section: identity
Name Type
canada_patent_number string canada_patent_type string patent_name string trial_manager_id string agent_company string secondary_agent_company string breeding_company string trademark_partial string us_patent_number string us_patent_type string genus string species string series string variety string trademark string common_name string brand string programs array of strings
Response section: characteristics
Name Type
flower_shade string foliage_shade string market_height_maximum integer habit string height_category string scape_height_maximum integer scape_height_minimum integer spacing_maximum integer duration string shrub_type string seasons array of strings market_height_minimum integer garden_height_minimum integer garden_height_maximum integer trails_up_to integer spacing_minimum integer spread_minimum integer spread_maximum integer flower_colors array of strings foliage_colors array of strings container_role string vigor_rating integer (1 - 4) or empty aggressive boolean
Response section: needs
Name Type
needs_good_drainage boolean water_category string maintenance_category string maintenance_notes string / HTML uses_notes string / HTML temperature_minimum integer temperature_maximum integer light_level array of strings blooms_on array of strings bloom_time array of strings hardiness_zones array of strings heat_zones array of strings soil_fertility array of strings soil_ph_category array of strings uses array of strings humidity_preference array of strings container_soil_type array of strings
plant_genus/list Get a list of plant genuses. Our list of genuses does not grow significantly over time. All genuses are returned. If your account has access to unpublished genuses, those will be included.
URL
https://www.provenwinners.com/api/v0/plant_genus/list
plant_series/list Get a list of plant series. Our list of series does not grow significantly over time. All series are returned. If your account has access to unpublished series, those will be included.
URL
https://www.provenwinners.com/api/v0/plant_series/list
plant_species/list Get a list of plant species. Our list of species does not grow significantly over time. All species are returned. If your account has access to unpublished species, those will be included.
URL
https://www.provenwinners.com/api/v0/plant_species/list
culture/search Get plant cultures, using general or specific parameters. Parameters combine in logical AND. To look up a particular culture, just provide a single NID or culture ID.
URL
https://www.provenwinners.com/api/v0/culture/search
Parameters
Name Type Description
changed_after unix timestamp | YYYY-MM-DD Anything changed after this date will be returned. cultureid array Culture IDs nid array NIDs sections array Optional sections to include with each culture: metrics.
Response Data
Name Type
nid integer cultureid integer published boolean title string changed timestamp created timestamp url string / URL metrics object: refer to section definition
Response section: metrics
Name Type
ph_categories array of strings ec_maximum number ec_minimum number fertilization_maximum number fertilization_minimum number finishing_time_12_inch string finishing_time_16_inch string finishing_time_2_inch string finishing_time_5_inch string finishing_time_6_inch string finishing_time_9_inch string grower_tips string / HTML growing_on_maximum number growing_on_minimum number holding_temp_maximum number holding_temp_minimum number over_wintering_temperature string pest_disease_management string / HTML ph_maximum number ph_minimum number pinching_growth_regulators string / HTML planting_and_timing string / HTML addition string / HTML rooting_temp_maximum number rooting_temp_minimum number spring_outdoor_finish string vernalization string winter_flowering boolean ec_categories array of strings fertilization_categories array of strings light_requirements array of strings plant_genus string water_requirements array of strings rooting_temp_categories array of strings plant_series string plant_species string plant_variety string growing_on_categories array of strings common_name string holding_temp_categories array of strings starting_materials array of strings photoperiod_for_flowering array of strings
shipment/update
This endpoint is solely for our vendors.
Vendors may use this endpoint to update the status of shipment fulfillments.
Vendors may post multiple complete or partial shipment fulfillments in a single call.
Shipments can be updated repeatedly with partial fulfillments, until completely fulfilled.
In the event of a partial shipment update, vendors should assign a unique
vendor_reference_id per update. This may occur, for example, when
splitting a shipment into stages.
Notes
The API key used for requests made to this endpoint must
be associated with a user associated with a ProvenWinners Vendor account.
This endpoint is functional but the test console embedded on this page is
currently non-functional, due to the extended input format.
URL
https://www.provenwinners.com/api/v0/shipment/update
Parameters
Name Type Description
shipments array An array of shipment update objects. Format as follows:
Key Type Description
order_id integer ProvenWinners order ID. shipment_id integer ProvenWinners shipment ID. actual_ship_date string Actual ship date in D/M/YYYY format. tracking_number string Optional. Shipment tracking identifier. actual_ship_amount number Actual shipping cost. actual_products_amount number Actual cost of products shipped. vendor_shipment_id string Optional. Vendor shipment identifier. Partial shipment fulfillments should have unique vendor shipment identifiers. If you pass a previously sent vendor shipment identifier, it will update the previous record. transit_days number Optional. Shipping transit days. Allows us to notify customers when we think a product will arrive. line_items array Included line items in shipment. See format table below.
Shipment line item objects follow the following format:
Key Type Description
sku string ProvenWinners item SKU. vendor_sku string Vendor item SKU. qty_ordered number Number of this item ordered. qty_shipped string Number of this item included. each_price integer/float Price of one of this line item
Sample Request
{
"apikey":"123456789012345678901234567890",
"shipments":[
{
"order_id":987654,
"shipment_id":12345,
"actual_ship_date":"12/24/2014",
"actual_ship_amount":12.95,
"actual_products_amount":99.98,
"vendor_shipment_id":"89571043-98520598",
"transit_days":2,
"line_items":[
{
"sku":"12345",
"vendor_sku":"A-12345678",
"qty_ordered":2,
"qty_shipped":1,
"each_price":1.50
},
{
"sku":"123456",
"vendor_sku":"123-ABC",
"qty_ordered":2,
"qty_shipped":1,
"each_price":1.50
}
]
},
{
"order_id":9876543,
"shipment_id":123456,
"actual_ship_date":"12/24/2014",
"actual_ship_amount":12.95,
"actual_products_amount":99.98,
"vendor_shipment_id":"ZXY-999",
"transit_days":2,
"line_items":[
{
"sku":"12345678ABC",
"vendor_sku":"ABC12345678",
"qty_ordered":1,
"qty_shipped":1,
"each_price":1.50
}
]
},
{
"order_id":13579,
"shipment_id":101010,
"actual_ship_date":"12/24/2014",
"actual_ship_amount":12.95,
"actual_products_amount":99.98,
"vendor_shipment_id":"20150225-76543",
"transit_days":3,
"line_items":[
{
"sku":"LMNOP-QRSTU",
"vendor_sku":"2000015",
"qty_ordered":1,
"qty_shipped":1,
"each_price":1.50
}
]
},
{
"order_id": 1,
"shipment_id": 1,
"actual_ship_date":"12/24/2014",
"actual_ship_amount":12.95,
"actual_products_amount":99.98,
"vendor_shipment_id":"1A",
"transit_days":2,
"line_items":[
{
"sku":"S1A",
"vendor_sku":"VS1A",
"qty_ordered":3,
"qty_shipped":2,
"each_price":1.50
}
]
}
]
}
Response Data
Name Type
errors array of strings warnings array of strings successes array of strings
inventory/update
This endpoint is for our vendors.
Vendors may use this endpoint to update our list of their inventory.
Updates overwrite inventory for SKUs included in the call.
SKUs that are left out of the call are not impacted,
even if they are assigned to the same vendor.
If you use the bucket data format, any buckets provided
for a SKU overwrite all buckets previously provided for a SKU.
The API key used for requests made to this endpoint must
be associated with a user associated with a ProvenWinners Vendor account.
URL
https://www.provenwinners.com/api/v0/inventory/update
Parameters
Name Type Description
inventory array An array of inventory objects.
You can use the SKU format or the bucket format,
but all rows must use the same format within the call.
SKU object format
This format supports one row per SKU.
Key Type Description
pw_sku string Proven Winners SKU. vendor_sku string Vendor SKU (can be same or different to PW SKU). inventory integer QTY in stock. status boolean Whether the product should be shown for sale. track_stock boolean Whether stock QTY matters. list_price float US Dollar value. cost float US Dollar value. How much you will charge PW per item. sell_price float US Dollar value. ready_date null|date A future date when this product will be available to ship. Enables pre-sell. Date format is MM/DD/YYYY. sku_comment string Purely for admin information.
Bucket object format
This format supports multiple rows per SKU.
It allows the vendor to control distributed quantities at various future ship dates.
Key Type Description
pw_sku string Proven Winners SKU. bucket_id string A unique ID for this bucket. Can include SKU. vendor_sku string Vendor SKU (can be same or different to PW SKU). inventory integer QTY in stock. status boolean Whether the product should be shown for sale. track_stock boolean Whether stock QTY matters. list_price float US Dollar value. cost float US Dollar value. How much you will charge PW per item. sell_price float US Dollar value. ready_date null|date A future date when this bucket of product will be available to ship. Enables pre-sell. Date format is MM/DD/YYYY. end_date null|date A future date when this bucket of product will stop being available to ship. Date format is MM/DD/YYYY. sku_comment string Purely for admin information.
Sample Request
{
"apikey": "123456789012345678901234567890",
"inventory": [
{
"pw_sku": "abc123",
"vendor_sku": "xyz987",
"inventory": 5,
"status": true,
"track_stock": true,
"list_price": 10.99,
"cost": 8,
"sell_price": 9.99,
"ready_date": "06/09/2024",
"sku_comment": "This is not a real update, it is just a test"
},
{
"pw_sku": "abc456",
"vendor_sku": "xyz654",
"inventory": 100,
"status": true,
"track_stock": true,
"list_price": 10.99,
"cost": 8,
"sell_price": 10.99,
"ready_date": "10/18/2023",
"sku_comment": ""
}
]
}
Response Data
Name Type
errors array of strings successes array of strings
light_levels/list Get a list of light levels. Our list does not grow significantly over time. All levels are returned. If your account has access to unpublished series, those will be included.
URL
https://www.provenwinners.com/api/v0/light_levels/list
