NAV
shell python

Introduction

Welcome to the Spring API! You can use our API to access Spring API endpoints, which can get information on various products in our database or create or update products for your brand on Spring.

We have language bindings in Bash and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

import spring

api = spring.ApiClient('f45h10nw33k')
# In shell, you can just pass your authentication credentials with each request.
# Make sure to put a : after your API key.
curl "api_endpoint_here" \
    -u "f45h10nw33k:"

Make sure to replace f45h10nw33k with your API key.

Spring uses API keys over HTTP Basic Authentication to allow access to our API. To obtain an API key, please email apisupport@shopspring.com.

Spring expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Basic ZjQ1aDEwbnczM2s6

Products

Get All Product IDs

import spring

api = spring.ApiClient('f45h10nw33k')
api.get_all_product_ids()
curl "https://vfe-demo.jellolabs.com:9000/api/1/product_ids" \
    -u "f45h10nw33k:"

The above command returns JSON structured like this:

{
    "product_ids": [
        "1ABC001",
        "2DEF002",
        "3FYL003"
    ]
}

This endpoint retrieves all product ids which were created using your API key.

HTTP Request

GET https://vfe-demo.jellolabs.com:9000/api/1/product_ids

Create or update a Product

import spring

api = spring.ApiClient('f45h10nw33k')
product = {
    'id': 'SOMEID123',
    'title': 'Cathat',
    'description': 'A Hat for a Cat!',
    'tags': ['hats', 'cats', 'headgear']
    'active': True,
    'purchasable': True,
    'variants': [
        {
            'available_inventory': 1000,
            'price': '14.95',
            'sku': '162636740101',
            'image_urls': [
                'http://example.com/images/cathat1,1.jpg',
                'http://example.com/images/cathat1,2.jpg',
                'http://example.com/images/cathat1,3.jpg'
            ],
            'attributes': {
                'color': 'Green',
                'size': 'ONESIZE',
            }
        },
        {
            'available_inventory': 1000,
            'price': '14.95',
            'sku': '162080212940',
            'image_urls': [
                'http://example.com/images/cathat2,1.jpg',
                'http://example.com/images/cathat2,2.jpg',
                'http://example.com/images/cathat2,3.jpg'
            ],
            'attributes': {
                'color': 'Purple',
                'size': 'ONESIZE',
            }
        }
    ]
}

vendor_id = 2525
api.update_product(product, vendor_id)
curl "https://vfe-demo.jellolabs.com:9000/api/1/product" \
    -u "f45h10nw33k:" \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '
{
    "vendor_id": 2525,
    "product": {
        "id": "SOMEID123",
        "title": "Cathat",
        "description": "A Hat for a Cat!",
        "tags": ["hats", "cats", "headgear"]
        "active": true,
        "purchasable": true,
        "variants": [
            {
                "available_inventory": 1000,
                "price": "14.95",
                "sku": "162636740101",
                "image_urls": [
                    "http://example.com/images/cathat1,1.jpg",
                    "http://example.com/images/cathat1,2.jpg",
                    "http://example.com/images/cathat1,3.jpg"
                ],
                "attributes": {
                    "color": "Green",
                    "size": "ONESIZE",
                }
            },
            {
                "available_inventory": 1000,
                "price": "14.95",
                "sku": "162080212940",
                "image_urls": [
                    "http://example.com/images/cathat2,1.jpg",
                    "http://example.com/images/cathat2,2.jpg",
                    "http://example.com/images/cathat2,3.jpg"
                ],
                "attributes": {
                    "color": "Purple",
                    "size": "ONESIZE",
                }
            }
        ]
    }
}'

The above command returns HTTP status code 200 on success. On failure, it will return a non-200 status code and detailed exception information in the body.

This endpoint creates a new product, or updates an existing product. The primary key for a product is the id field.

NOTE: This endpoint can also undelete products that are deleted by the "Delete Product" endpoint, or deleted automatically by Spring because of not have been updated for a continuous 3 days.

HTTP Request

PUT https://vfe-demo.jellolabs.com:9000/api/1/product

Request Body JSON Schema

Argument (type) Required / Optional Description
vendor_id (integer) Required Unique brand account identifier (issued by Spring)
product (JSON) Required A JSON object containing the product you want to send to Spring

Product Schema

Field Name (type, length) Required / Optional Description
id (string, no length restriction) Required Integrated product ID (typically a unique style # or master product identifier in the brand system)
title (string, max_length=255) Required Product name
description (string, no length restriction) Required Product description
active (boolean) Required Sets product visibility: use true to specify that the product is viewable, even if isn’t currently purchasable, e.g. in case of backorder; use false to hide the product
purchasable (boolean) Required Sets product purchasability: use true if the product can be purchased on the brand site (i.e. is not on backorder); use false to mark the product OOS on Spring
external_brand (string, no length restriction) Required Required, but can be set to NULL (specifies the brand/label or manufacturer of the product, e.g. Polo Ralph Lauren vs. Ralph Lauren Black Label)
affiliate_url (string) Required Product page URL or affiliate network-tracked link for the product
photo_urls (list of strings, no length restriction) Required List of product image URLs
tags (list of strings, string has no length restriction) Required List of product categories
variants (list of variants – see below) Required A product should at least have one variant

Variant Schema

Field Name (type, length) Required / Optional Description
sku (string, max_length=255) Required Variant SKU, variants belonging to the same product should have different SKUs
original_price (decimal) Optional Variant original price (use to represent list price, when SKU is on sale; can also be set to the same value as price when SKU is not on sale)
price (decimal) Required Variant price, currently Spring only allows the same price for all variants of a product
available_inventory (integer) Required Variant level inventory quantity available to sell
size (string, max length=30) Required Variation attribute values combination used for display to Spring user, e.g. for a size 7 Black color shoe, this should be “Black 7”
attributes (JSON) Optional JSON object containing variation attributes as name/value pairs

Delete a Product


import spring

api = spring.ApiClient('f45h10nw33k')
api.delete_product('SOMEID123')
curl "https://vfe-demo.jellolabs.com:9000/api/1/product/SOMEID123" \
    -u "f45h10nw33k:" \
    -X DELETE \
    -H "Content-Type: application/json"

HTTP Request

DELETE https://vfe-demo.jellolabs.com:9000/api/1/product/<ID>

URL Parameters

Parameter Description
ID The ID of the product to delete.

NOTE: To avoid stale product data, products that have not been updated for a continuous 3 days will be automatically deleted.

Errors

The Spring API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request had no API key
403 Forbidden – Your API key is wrong
500 Internal Server Error – We had a problem with our server. Try again later.