Zippin APIs

The Zippin API is organized around REST. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

storeId is refers to tenant store id.

Authentication

The Zippin API uses API keys to authenticate requests. Contact your Zippin representative to get the API keys.

Keep your API keys secure!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Zippin API uses standard HTTP response codes to indicate the success or failure or an API request.

Code	Meaning
200 - OK	Everything worked as expected.
400 - Bad Request	Invalid request.
401 - Unauthorized	Provided API key is invalid.
404 - Not Found	The requested resource could not be found.
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Internal Server Error	Something went wrong on Zippin's end.

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. These list API methods share a common structure, taking these two parameters: limit and offset.

Parameter	Type	Description
limit	integer	(Optional) A limit on the number of records to be returned, between 1 and 100. Default is 100.
offset	integer	(Optional) Offset is the start record id for the list of records to return. Default is 0. For instance, if you make a list request and receive 100 records, then, your subsequent call can include offset=100 in order to fetch the next page of the list.

Get QR Code for the shopper

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/2462ff0d-723a-4713-a128-6c1d0fc226/code" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
  "userToken": "2462ff0d-723a-4713-a128-6c1d0fc226",
  "code": "v1:zipp:2462ff0d-723a-4713-a128-6c1d0fc226:1567628198079:L5rM/q2Q4NqIKDmsKAd9Vsw5hPHB1YKJ95ea8odOroic/SGRSs1zeQ=="
}

To enter the store, user scans a secure QR code. QR code has the expiry time.

Call this Zippin API from your secure backend service and pass the QR code to the shopper, usually over a mobile application. Refresh QR code every minute while shopper is on QR code screen.

Keep your API keys secure! Do not expose API keys to the frontend applications.

Alternatively, you can generate the token in your backend service using pre-shared DSA key-pairs. You will generate the token using private key and Zippin will use public key to validate the token. Reach out to Zippin team to learn more about this option.

Request

URL

GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/<userToken>/code

URL Parameters

Parameter	Type	Description
userToken	string	Identifies user entering the store.

Response

Returns user token and code. This code should be displayed as a QR code and scanned at the store to enter.

Attributes

Attribute	Type	Description
userToken	string	Identifies user entering the store.
code	string	The QR code used to enter the store.

Dispute Cart

curl -X POST \
 "https://us-central1-zyp-store.cloudfunctions.net/api/v1/stores/store123/carts/o-47132462ff0d-723a/dispute" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '{
        "item": "COKE",
        "quantity": 1,
        "email" : "ram@example.com",
        "description" : "I never took a Coke!!!"
    }'

{
    "cartId": "o-47132462ff0d-723a",
    "message": "Cart dispute created successfully."
}

When you get a dispute request, you can use this Zippin API to submit with requested details to help us resolve the dispute.

Request

URL

POST https://us-central1-zyp-store.cloudfunctions.net/api/v1/stores/<Store ID>/carts/<Cart ID>/dispute

URL Parameters

Parameter	Type	Description
Store ID	string	The identifier of the store.
Cart ID	string	Zippin cart id for this shopping session.

Request Attributes

Attribute	Type	Description
item	string	The tenant SKU ID.
quantity	number	The quantity of the SKU.
email	string	The email address of the customer.
description	string	The reason for the dispute.

Response

Returns the cartId and message if succeeded. Throws an error if parameters are invalid (e.g. specifying an invalid item, invalid cartId, Invalid quantity etc).

Attributes

Attribute	Type	Description
cartId	string	Zippin cart id for this shopping session.
message	string	The status message of the cart dispute request.

Catalog

Add a SKU

curl -X POST \
  "https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "KQS2X12",
    "name": "Kale and Quinoa Salad",
    "unitWeight": 253,
    "thumbnails": ["https://images.example.com/kq132.jpg", "https://images.example.com/kq112.jpg"],
    "force": true,
    "storeIds": ["teststore1", "teststore2"],
    "price": 5,
    "taxRate": 8.75,
    "categories": ["miscellaneous"]
  }'

{
    "id": "KQS2X12",
    "name": "Kale and Quinoa Salad",
    "created": 1552088527,
    "updated": 1552088527,
    "deleted": false,
    "unitWeight": 253,
    "thumbnails": ["https://images.example.com/kq1.jpg", "https://images.example.com/kq1.jpg"],
    "storeIds": ["teststore1", "teststore2"],
    "price": 5,
    "taxRate": 8.75,
    "categories": ["miscellaneous"]
}

Creates the specified SKU by setting the values of the parameters passed.

Request

URL

POST https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/

Request Attributes

Attribute	Type	Description
id	string	The identifier of the SKU. Must be 1–16 characters.
name	string	The name of the SKU.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
force	boolean	Optional. Pass force = true to reuse the same SKU that has been archived.
storeIds	array	Optional. An array of store ids. Defaults to all stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	Optional. An array of category codes. Defaults to default category.

Response

Returns the SKU object if the create succeeded. Throws an error if create parameters are invalid.

Response Attributes

Attribute	Type	Description
id	string	The identifier of the SKU.
name	string	The name of the SKU.
created	string	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	string	Time at which the object was updated. Measured in seconds since the Unix epoch.
deleted	boolean	The deleted status of the SKU.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
storeIds	array	An array of store ids or null for all stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	An array of category codes.

Update a SKU

curl -X PUT \
  "https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/<SKU ID>" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kale and Quinoa Salad",
    "unitWeight": 253,
    "thumbnails": ["https://images.example.com/kq132.jpg", "https://images.example.com/kq112.jpg"],
    "storeIds": ["teststore1", "teststore2"],
    "price": 5,
    "taxRate": 8.75,
    "categories": ["miscellaneous"]
  }'

{
    "id": "KQS2X12",
    "name": "Kale and Quinoa Salad",
    "created": 1552088527,
    "updated": 1552088527,
    "deleted": false,
    "unitWeight": 253,
    "thumbnails": ["https://images.example.com/kq1.jpg", "https://images.example.com/kq1.jpg"],
    "storeIds": ["teststore1", "teststore2"],
    "price": 5,
    "taxRate": 8.75,
    "categories": ["miscellaneous"]
}

Updates the specified SKU by setting the values of the parameters passed. This request accepts mostly the same arguments as the SKU creation call.

Request

URL

PUT https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/<SKU ID>

URL Parameters

Parameter	Type	Description
SKU ID	string	The identifier of the SKU.

Request Attributes

Attribute	Type	Description
name	string	The name of the SKU.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
storeIds	array	Optional. An array of store ids. Defaults to all stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	Optional. An array of category codes. Defaults to default category.

Response

Returns the SKU object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid SKU ID).

Response Attributes

Attribute	Type	Description
id	string	The identifier of the SKU.
name	string	The name of the SKU.
created	string	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	string	Time at which the object was updated. Measured in seconds since the Unix epoch.
deleted	boolean	The deleted status of the SKU.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
storeIds	array	An array of store ids or null for all stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	An array of category codes.

Retrieve a SKU

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/<SKU ID>" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
    "id": "KQS2X12",
    "name": "Kale and Quinoa Salad",
    "created": 1552088527,
    "updated": 1552088527,
    "deleted": false,
    "unitWeight": 253,
    "thumbnails": ["https://images.example.com/kq1.jpg", "https://images.example.com/kq1.jpg"],
    "storeIds": ["teststore1", "teststore2"],
    "price": 5,
    "taxRate": 8.75,
    "categories": ["miscellaneous"]
}

Retrieves the details of an existing SKU. You need only supply the unique SKU identifier that was passed during the SKU creation.

Request

URL

GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/<SKU ID>

URL Parameters

Parameter	Type	Description
SKU ID	string	The identifier of the SKU.

Response

Returns the SKU object if a valid identifier was provided. Throws an error if the ID of a SKU is invalid.

Response Attributes

Attribute	Type	Description
id	string	The identifier of the SKU.
name	string	The name of the SKU.
created	string	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	string	Time at which the object was updated. Measured in seconds since the Unix epoch.
deleted	boolean	The deleted status of the SKU.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
storeIds	array	An array of store ids or null for all stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	An array of category codes.

List all SKUs

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus?limit=100&offset=0" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
  "totalRecords": 3,
  "fetchedRecords": 3,
  "skus": [
    {
        "id": "KQS2X12",
        "name": "Kale and Quinoa Salad",
        "created": 1552088527,
        "updated": 1552088527,
        "deleted": false,
        "unitWeight": 253,
        "thumbnails": ["https://images.example.com/kq1.jpg", "https://images.example.com/kq1.jpg"],
        "storeIds": ["teststore1", "teststore2"],
        "price": 5,
        "taxRate": 8.75,
        "categories": ["miscellaneous"]
    },
    {...},
    {...}
  ]
}

Returns a list of all SKUs. The SKUs are returned sorted by creation time. Any parameters not provided then it will return with 1-100 records.

Request

URL

GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus?limit=100&offset=0

URL Parameters

Parameter	Type	Description
limit	integer	(Optional) A limit on the number of records to be returned, between 1 and 100. Default is 100.
offset	integer	(Optional) Offset is the start record id for the list of records to return. Default is 0.

Response

A associative array with a skus property that contains an array of up to limit SKUs, starting after SKU offset. Each entry in the array is a separate SKU object. If no more SKUs are available, the resulting array will be empty. This request should never throw an error.

Response Attributes

Attribute	Type	Description
id	string	The identifier of the SKU.
name	string	The name of the SKU.
created	string	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	string	Time at which the object was updated. Measured in seconds since the Unix epoch.
deleted	boolean	true.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
totalRecords	integer	Total number of records available.
fetchedRecords	integer	Total number of records fetched based on the parameters passed.
storeIds	array	An array of store ids or null for all stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	An array of category codes.

Delete a SKU

curl -X DELETE "https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/<SKU ID>" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
    "id": "KQS2X12",
    "name": "Kale and Quinoa Salad",
    "created": 1552088527,
    "updated": 1552088527,
    "deleted": true,
    "unitWeight": 253,
    "thumbnails": ["https://images.example.com/kq1.jpg", "https://images.example.com/kq1.jpg"],
    "storeIds": ["teststore1", "teststore2"],
    "price": 5,
    "taxRate": 8.75,
    "categories": ["miscellaneous"]
}

Deletes a SKU if SKU has not been used in a cart. If this SKU has been used in a cart, it will not be deleted, however, it will be marked deleted.

Request

URL

DELETE https://us-central1-zyp-store.cloudfunctions.net/api/v1/skus/<SKU ID>

URL Parameters

Parameter	Type	Description
SKU ID	string	The identifier of the SKU.

Response

Returns an object with a deleted SKU on success. If the SKU ID does not exist, this call throws an error.

Response Attributes

Attribute	Type	Description
id	string	The identifier of the SKU.
name	string	The name of the SKU.
created	string	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	string	Time at which the object was updated. Measured in seconds since the Unix epoch.
deleted	boolean	true.
unitWeight	number	The unit weight of the SKU in grams.
thumbnails	array	An array of thumbnail jpg urls for the SKU.
storeIds	array	An array of store ids. If attribute is not passed, sku is available for all your stores.
price	number	Optional. The base price of the SKU. Ex: ”price”: 5 represents $5. Currency is set at the store level.
taxRate	number	Optional. The percentage tax rate applied to the sku. Defaults to 0. Ex: ”taxRate”: 8.75 represents 8.75%. If the decimal places more than 2 then it will get rounded off to 2 decimal places. For example, 8.759 will be rounded off to 8.76 and 8.751 will be rounded off to 8.75.
categories	array	An array of category codes.

Attribute	Type	Description
name	string	The name of the SKU category.
code	string	The code of the SKU category.
isDefault	boolean	Only one category should be default. Default category will be associated with SKU if it's not provided during the SKU creation or updation.

Shelf Inventory

Retrieve inventory on a shelf

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/stores/<Store ID>/shelves/<Shelf ID>" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
    "storeId": "S6241",
    "shelfId": "10101",
    "defaultSKU": "KQS2X12",
    "items": [
      {"sku": "KQS2X12", "quantity":  10},
      {"sku": "E2S2X12", "quantity":  2}
      ],
    "updated": 1552088527
}

Retrieves the details of an existing shelf. You need only supply the unique store identifier and shelf identifier.

Request

URL

GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/stores/<Store ID>/shelves/<Shelf ID>

URL Parameters

Parameter	Type	Description
Store ID	string	The identifier of the store.
Shelf ID	string	The identifier of the shelf.

Response

Returns a shelf object if a valid identifier was provided. Throws an error if the ID of a store or shelf is invalid.

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
shelfId	string	The identifier of the shelf.
defaultSKU	string	The default SKU ID for the shelf.
items	array	An array of items (SKU and quantity) on the shelf.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.

Retrieve inventory on all shelves

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/stores/<Store ID>/shelves?limit=100&offset=0" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
    "totalRecords": 2,
    "fetchedRecords": 2,
    "storeId": "store123",
    "shelves": [
        {
            "shelfId": "10101",
            "items": [
                {
                    "sku": "COKECAN",
                    "quantity": 1
                }
            ],
            "updated": 1575724057,
            "defaultSKU": "COKECAN"
        },
        {
            "shelfId": "10102",
            "items": [
                {
                    "sku": "DTCOKECAN",
                    "quantity": 1
                }
            ],
            "updated": 1552088527,
            "defaultSKU": "DTCOKECAN"
        }
    ]
}

Lists shelf inventory for the requested store.

Request

URL

GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/stores/<Store ID>/shelves?limit=100&offset=0

URL Parameters

Parameter	Type	Description
Store ID	string	The identifier of the store.
limit	integer	(Optional) A limit on the number of records to be returned, between 1 and 100. Default is 100.
offset	integer	(Optional) Offset is the start record id for the list of records to return. Default is 0.

Response

List of shelves in the requested store.

Response Attributes

Attribute	Type	Description
storeId	string	Store ID.
shelfId	string	Shelf ID.
defaultSKU	string	The default SKU ID for the shelf.
items	array	An array of items (SKU and quantity) on the shelf.
updated	timestamp	Timestamp when shelf was updated. Seconds since Unix epoch.
totalRecords	integer	Total number of records available.
fetchedRecords	integer	Number of records fetched.

Update SKU on a shelf

curl -X PUT \
  "https://us-central1-zyp-store.cloudfunctions.net/api/v1/shelves" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '[{
      "storeId": "store123",
      "shelves": [
          {
              "shelfId": "10102",
              "sku": "BOSBLKCFF"
          },
          {
              "shelfId": "10103",
              "sku": "7894900031607"
          }
      ]
    },
    {
      "storeId": "store456",
      "shelves": [
          {
              "shelfId": "10201",
              "sku": "CAN78949"
          },
          {
              "shelfId": "10202",
              "sku": "BOSB31607"
          }
      ]
    }]'

[{
    "storeId": "store123",
    "shelves": [
        {
            "shelfId": "10102",
            "items": [{"sku": "BOSBLKCFF", "quantity": 3}],
            "updated": "1572463626416",
            "defaultSKU": "BOSBLKCFF"
        },
        {
            "shelfId": "10103",
            "items": [{"sku": "7894900031607", "quantity": 1}],
            "updated": "1572463624404",
            "defaultSKU": "7894900031607"
        }
     ]
},
{
    "storeId": "store456",
    "shelves": [
        {
            "shelfId": "10201",
            "items": [{"sku": "CAN78949", "quantity": 2}],
            "updated": "1572463626416",
            "defaultSKU": "CAN78949"
        },
        {
            "shelfId": "10202",
            "items": [{"sku": "BOSB31607", "quantity": 4}],
            "updated": "1572463624404",
            "defaultSKU": "BOSB31607"
        }
     ]
}]

Updates SKU on the shelf if shelf has only default SKU items. This request accepts one or more stores.

Request

URL

PUT https://us-central1-zyp-store.cloudfunctions.net/api/v1/shelves

Request Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
shelfId	string	The identifier of the shelf.
sku	string	The default SKU ID for the shelf.

Response

Returns the shelf object if the update succeeded. Throws an error if update parameters are invalid (e.g. if shelf has multiple SKUs or SKU is deleted).

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
shelfId	string	The identifier of the shelf.
defaultSKU	string	The default SKU ID for the shelf.
items	array	An array of items (SKU and quantity) on the shelf.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.

User

All users are shoppers unless assigned a specific role by calling this API. If you want to change role for a user back to shopper, simply delete the user.

Add Users

curl -X POST \
  "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '[{
        "storeId": "store123",
        "users" : [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "admin"
        }]
      },
      {
        "storeId": "store456",
        "users" : [
        {
            "userToken": "a6de9a2a-84fd-4819-b5b8-5fefb3e23010",
            "role": "tester"
        }]
      }]'

[{
    "storeId": "store123",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "admin",
            "created": 1575723426,
            "updated": 1575723426
        }
    ]
},
{
    "storeId": "store456",
    "users" : [
        {
            "userToken": "a6de9a2a-84fd-4819-b5b8-5fefb3e23010",
            "role": "tester",
            "created": 1575723426,
            "updated": 1575723426
        }
    ]
}]

Adds the specified users by setting the values of the parameters passed.

Request

URL

POST https://us-central1-zyp-store.cloudfunctions.net/api/v1/users

Request Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.

Response

Returns the user object array if the create succeeded. Throws an error if create parameters are invalid (e.g. specifying an invalid storeId or an invalid role).

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.
created	timestamp	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.

Update Users

curl -X PUT \
  "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '[{
        "storeId": "store123",
        "users" : [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "tester"
        }]
      },
      {
        "storeId": "store456",
        "users" : [
        {
            "userToken": "a6de9a2a-84fd-4819-b5b8-5fefb3e23010"
        }]
      }]'

[{
    "storeId": "store123",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "tester",
            "created": 1575724029,
            "updated": 1575724057
        }
    ]
},
{
    "storeId": "store456",
    "users" : [
        {
            "userToken": "a6de9a2a-84fd-4819-b5b8-5fefb3e23010",
            "role": "tester",
            "created": 1575723426,
            "updated": 1575723426
        }
    ]
}]

Updates the specified users by setting the values of the parameters passed. If the role parameter is not provided then the specified user will be deleted from the store and the user will be treated as a shopper by the system.

Request

URL

PUT https://us-central1-zyp-store.cloudfunctions.net/api/v1/users

Request Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.

Response

Returns the user object array if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid storeId or an invalid userToken or an invalid role).

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.
created	timestamp	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.

Retrieve a User

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/9fabb8f0-2de1-4b75-9d3c-d5ddc1467999" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

[{
    "storeId": "store123",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "tester",
            "created": 1575724029,
            "updated": 1575724057
        }
    ]
},
{
    "storeId": "store456",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "admin",
            "created": 1575724029,
            "updated": 1575724057
        }
    ]
}]

Retrieves the details of an existing user. You need only supply the unique user identifier that was passed during the user creation.

Request

URL GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/<userToken>

URL Parameters

Parameter	Type	Description
userToken	string	The identifier of the user.

Response

Returns the user object array if a valid identifier was provided. Throws an error if the ID of a user is invalid.

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.
created	timestamp	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.

List all Users

curl "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users?limit=100&offset=0" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

{
    "totalRecords": 2,
    "fetchedRecords": 2,
    "users": [
        {
            "storeId": "store123",
            "users": [
                {
                    "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
                    "role": "tester",
                    "created": 1575724029,
                    "updated": 1575724057
                }
            ]
        },
        {
            "storeId": "store456",
            "users": [
                {
                    "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
                    "role": "admin",
                    "created": 1575724029,
                    "updated": 1575724057
                }
            ]
        }
    ]
}

Returns a list of your users. The users are returned sorted by creation time. Any parameters not provided then it will return with 1-100 records.

Request

URL

GET https://us-central1-zyp-store.cloudfunctions.net/api/v1/users?limit=100&offset=0

URL Parameters

Parameter	Type	Description
limit	integer	(Optional) A limit on the number of records to be returned, between 1 and 100. Default is 100.
offset	integer	(Optional) Offset is the start record id for the list of records to return. Default is 0.

Response

A associative array with a users property that contains an array of up to limit users, starting after user offset. Each entry in the array is a separate user object. If no more users are available, the resulting array will be empty. This request should never throw an error.

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.
created	timestamp	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.
totalRecords	integer	Total number of records available.
fetchedRecords	integer	Total number of records fetched based on the parameters passed.

Delete a User

curl -X DELETE "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/9fabb8f0-2de1-4b75-9d3c-d5ddc1467999" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d"

[{
    "storeId": "store123",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "tester",
            "created": 1575724029,
            "updated": 1575724057
        }
    ]
},
{
    "storeId": "store456",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "admin",
            "created": 1575724029,
            "updated": 1575724057
        }
    ]
}]

Permanently deletes a user across the stores. It cannot be undone and the user will be treated as a shopper by the system.

Request

URL

DELETE https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/<userToken>

URL Parameters

Parameter	Type	Description
userToken	string	The identifier of the user.

Response

Returns the user object array if the delete succeeded. Throws an error if the user token is invalid.

Response Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
role	string	The user's role name. One of admin or tester.
created	timestamp	Time at which the object was created. Measured in seconds since the Unix epoch.
updated	timestamp	Time at which the object was updated. Measured in seconds since the Unix epoch.

Open Store Entrance

curl -X POST "https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/9fabb8f0-2de1-4b75-9d3c-d5ddc1467999/enter" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json" \
  -d '{
        "entryCode": "123456"
      }'

200 OK

Opens the store entrance for the matching entry code.

Request

URL

POST https://us-central1-zyp-store.cloudfunctions.net/api/v1/users/<userToken>/enter

URL Parameters

Parameter	Type	Description
userToken	string	Identifies user entering the store.
entryCode	string	Entry code of the store entrance.

Response

Returns 200 status on success. If the user token or entry code does not exist, this call throws an error.

Retailer APIs

You will implement these APIs and provide endpoints to the Zippin.

Cart Submission

curl -X POST \
  "https://api.retailer.example.com/v1/users/2462ff0d-723a-4713-a128-6c1d0fc226/cart" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "S6241",
    "entryTimestamp": 1552088527,
    "exitTimestamp": 1552088527,
    "cartId": "o-0e674fdf-f27e-4a39-9c3d-46ec59a361df",
    "items": [
        {
            "sku": "FAY010008147",
            "quantity": 1
        },
        {
            "sku": "789CXP008147",
            "quantity": 2
        }
    ]
  }'

{
  "orderId": "47132462ff0d-723a"
}

Zippin calls your API to submit the cart after shopper leaves the store.

This API may be called multiple times for same cartId. On subsequent call with same cartId, shopper must be billed only if not billed earlier for this cartId.

The response orderId is unique for this cartId. This orderId must be the same if this API is called again for same cartId.

Request

URL

POST https://api.retailer.example.com/v1/users/<userToken>/cart

URL Parameters

Parameter	Type	Description
userToken	string	Identifies the user who is responsible for this cart.

Request Attributes

Attribute	Type	Description
storeId	string	The identifier of the store.
entryTimestamp	timestamp	Entry time of the object. Measured in seconds since the Unix epoch.
exitTimestamp	timestamp	Exit time of the object. Measured in seconds since the Unix epoch.
cartId	string	Zippin cart id for this shopping session.
items	array	(Optional) An array of items (SKU and quantity) in the cart. This will be empty when cart does not have any items.

Response

Optionally returns a retailer Order ID unique for the submitted cartId.

Response Attributes

Attribute	Type	Description
orderId	string	(Optional) The retailer Order ID unique for the cart.

Notifications

curl -X POST \
  "https://api.retailer.example.com/v1/notifications" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "entry",
    "storeId": "store123",
    "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
    "timestamp": 1529572012,
    "cartId": "o-a61fb38a-7ae8-4bdc-8c1b-bb771691d92f"
  }'

200 OK

Zippin calls your API to send the user entry and exit event notifications. This API will not be called again in case of failure.

Request

URL

POST https://api.retailer.example.com/v1/notifications

Request Attributes

Attribute	Type	Description
type	string	The type of the event. One of "entry" or "exit".
storeId	string	The identifier of the store.
userToken	string	The identifier of the user.
timestamp	timestamp	Entry or exit time of the event. Measured in seconds since the Unix epoch.
cartId	string	The identifier of the cart.

Response

Returns the success or failure status code.

Zippin APIs

Authentication

Errors

Get QR Code for the shopper

Dispute Cart

Catalog

Add a SKU

Update a SKU

Retrieve a SKU

List all SKUs

Delete a SKU

Categories

List all categories

Shelf Inventory

Retrieve inventory on a shelf

Retrieve inventory on all shelves

Update SKU on a shelf

User

Add Users

Update Users

Retrieve a User

List all Users

Delete a User

Open Store Entrance

Retailer APIs

Cart Submission

Notifications