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

Authentication is provided using standard Bearer API Tokens passed in through headers in the HTTP request. API tokens are secrets and should be protected similar to passwords. Do not share or distribute the API tokens where unauthorized parties can see it. This includes GitHub, Client Code, Log Files, etc.

All API requests should be made over HTTPS however this may not be available in-store. In this case HTTP requests would be allowed.

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

Errors

Standard conventional HTTP response codes are used to indicate the success or failure of an API request.

2xx range indicate success. 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). 5xx range indicate an error with the API Server(s).

Code	Meaning
200 - OK	Everything worked as expected.
201 - Created	An object was created successfully.
400 - Bad Request	Invalid request. Typically a missing required parameter.
401 - Unauthorized	Provided API key is invalid.
402 - Request Failed	Parameters are valid but the request failed.
403 - Forbidden	The API key does not have permissions to perform the request.
404 - Not Found	The requested resource could not be found.
409 - Conflict	The request has a conflict with another existing request.
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Internal Server Error	The API server experienced a problem.

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

The Dispute Object

Attribute	Type	Description
id	string	The identifier of the dispute.
sku	string	The tenant SKU ID.
quantity	number	The quantity of the SKU.
action	"add" or "remove"	The action to be taken on the item. For example, say quantity is 2. If action is "add" (shopper was under-billed), item count in the cart is increased by 2. If action is "remove" (shopper was over-billed), item count in the cart is reduced by 2.
description	string	The reason for the dispute.
status	"requested" or "approved" or "rejected"	The status for the dispute. The dispute request gets created with "requested" status, "approved" in case any discrepancy in the cart and "rejected" in case there is no discrepancy.
review_notes	string	The reason given by the dispute reviewer.

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 '{
        "email" : "ram@example.com",
        "disputes": [
            {
                "sku": "COKE",
                "quantity": 1,
                "action": "remove",
                "description" : "I took only 1 coke but I was charged for 2."
            },
            {
                "item": "DIETCOKE",
                "quantity": 1,
                "action": "add",
                "description" : "I took 1 diet coke but it's not included in the cart."
            },
            {...},
            {...}
        ]
    }'

{
    "cartId": "o-47132462ff0d-723a",
    "disputes": [
      {
          "id": "1621850561_COKE",
          "sku": "COKE",
          "quantity": 1,
          "action": "remove",
          "description": "I took only 1 coke but I was charged for 2.",
          "status": "requested"
      },
      {
          "id": "1621850561_DIETCOKE",
          "sku": "DIETCOKE",
          "quantity": 1,
          "action": "add",
          "description": "I took 1 diet coke but it's not included in the cart.",
          "status": "requested"
      },
      {...},
      {...}
    ],
    "email": "ram@example.com"
}

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
email	string	The email address of the customer.
disputes	array	An array of dispute object

Response

Returns dispute object array if succeeded for the specified cartId and email. Throws an error if parameters are invalid (e.g. specifying an invalid sku, cartId, 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. Maximum size of a thumbnail is 1MB.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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. Maximum size of a thumbnail is 1MB.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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%. Supports upto 4 decimal places and if the decimal places more than 4 then it will get rounded off to 4 decimal places. For example, 8.75968 will be rounded off to 8.7597 and 8.75124 will be rounded off to 8.7512.
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 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",
              "quantity": 5,
              "capacity": 50000
          },
          {
              "shelfId": "10103",
              "sku": "7894900031607"
          }
      ]
    },
    {
      "storeId": "store456",
      "shelves": [
          {
              "shelfId": "10201",
              "sku": "CAN78949",
              "quantity": 5
          },
          {
              "shelfId": "10202",
              "capacity": 10000
          }
      ]
    }]'

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

Update default SKU, quantity and capacity on the shelf. This request accepts one or more stores and shelves. shelfId and sku attributes are required to update default SKU; shelfId, sku and quantity attributes are required to update SKU quantity; shelfId and capacity attributes are required to update shelf capacity.

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.
quantity	number	The quantity of the SKU.
capacity	number	The capacity of a shelf in grams.

Response

Returns the shelf object if the update succeeded. Throws an error if update parameters are invalid (e.g. shelf is not found or SKU is deleted or invalid quantity or invalid capacity).

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.
capacity	number	The capacity of a shelf in grams.

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": "admin"
        }]
      }]'

[{
    "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": "admin",
            "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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.

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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.
created	timestamp	Timestamp when user was enrolled as store crew. Measured in seconds since the Unix epoch.
updated	timestamp	Timestamp when user role 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": "admin"
        }]
      },
      {
        "storeId": "store456",
        "users" : [
        {
            "userToken": "a6de9a2a-84fd-4819-b5b8-5fefb3e23010"
        }]
      }]'

[{
    "storeId": "store123",
    "users": [
        {
            "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
            "role": "admin",
            "created": 1575724029,
            "updated": 1575724057
        }
    ]
},
{
    "storeId": "store456",
    "users" : [
        {
            "userToken": "a6de9a2a-84fd-4819-b5b8-5fefb3e23010",
            "role": "admin",
            "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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.

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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.
created	timestamp	Timestamp when user was enrolled as store crew. Measured in seconds since the Unix epoch.
updated	timestamp	Timestamp when user role 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": "admin",
            "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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.
created	timestamp	Timestamp when user was enrolled as store crew. Measured in seconds since the Unix epoch.
updated	timestamp	Timestamp when user role 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": "admin",
                    "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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.
created	timestamp	Timestamp when user was enrolled as store crew. Measured in seconds since the Unix epoch.
updated	timestamp	Timestamp when user role 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": "admin",
            "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	admin	By sending role as `admin`, the user with the given userToken is enrolled as `Store Crew`.
created	timestamp	Timestamp when user was enrolled as store crew. Measured in seconds since the Unix epoch.
updated	timestamp	Timestamp when user role 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.

Reports

Reports enable you to generate analytical and performance specific reports that help understand a customers action in the store, customer entry throughput, and more. It also helps in generating various types of reports with the following information:

Sales data
Popular and trending products
Repeat customers
Average shopping time

You can use the following information to access these reports and data:

The Cart Object

Attribute	Type	Description
cartId	string	The Zippin cart identifier for a shopping session.
userToken	string	Identifies the user who is responsible for this cart.
items	array	A list of items in the cart. This field is blank in case there are no items in the cart.
status	string	The status of the cart. The status can be Submitted, Submission failed, Ready for billing, Failed, Partial or Paid.
storeId	string	The identifier of the Zippin store.
timezone	string	The local time zone of the store. For example, "America/Los_Angeles".
entryTimestamp	timestamp	Date and time of the shopper entry. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
exitTimestamp	timestamp	Date and time of the shopper exit. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
totalItems	number	The total quantity of items purchased per cart.
processedDate	string	Date and time the cart was processed. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
updatedAt	timestamp	Timestamp when the cart was last updated. It is measured in seconds from the Unix epoch.
loyaltyMembership	object	An object containing a list of loyalty IDs and loyalty provider/partner ID of the third party loyalty membership program. In case of group shopping, it is the membership ID of the shopper who is charged. This field is blank in case the loyalty membership code is not scanned by the shopper while shopping.
grossAmount	number	The total amount of all the items purchased, regardless of whether or not payment succeeded, and before discounts and refunds including tax. In the UI, this field is represented as Gross Receipts.
grossTax	number	The applicable tax component of gross receipts.
grossTaxes	array	Optional. The applicable tax component of gross receipts at tax type level. This applies only to carts charged using Zippin's billing system.
receivedTaxes	array	Optional. The tax component of the received amount at tax type level. This applies only to carts charged using Zippin's billing system.
discount	number	The total discounts applied on purchased items.
loyalty	number	The total loyalty amount applied on purchased items.
declinedAmount	number	The total amount submitted to the payment gateway or processor that was declined. Partial or the total amount may be automatically resubmitted after a short period of time and subsequently be approved. In the UI, this field is represented as Declined Payments.
refundAmount	number	The items returned before the payment is submitted or failed payments, thus reducing the shopper's payment, or after the shopper has paid. This can be items returned and amount both. In the UI, this field is represented as Refunds.
refundBackToCard	number	The amount of money refunded to a shopper's credit card after the shopper has made the payment. The value may be zero or less if the cart has declined payments.
receivedAmount	number	The net amount received after deducting discounts, loyalty, declined payments, and refunds, then adding received tax.
receivedTax	number	The tax component of the received amount.
gratuity	number	Optional. The applicable gratuity component of gross receipts. This applies only to carts charged using Zippin's billing system.
receivedGratuity	number	Optional. The gratuity component of the received amount. This applies only to carts charged using Zippin's billing system.
paymentGatewayName	string	The name of the payment gateway used to charge a cart.
errorCode	string	The error code from the payment gateway for a failed payment of a cart.
errorMessage	string	The error message from the payment gateway for a failed payment of a cart.
underReview	number	The total amount that is under review when processing the dispute request.
isOfflineTransaction	bool	Indicates whether the auth transaction was processed in offline mode or not.
payments	array	A list of payment objects.
refunds	array	An list of refunds objects.

The Cart Item Object

Attribute	Type	Description
sku	string	The unique ID of the SKU (stock keeping units) that identifies an item in the cart.
name	string	The name of the SKU.
categories	array	A list of category objects. A single SKU can have multiple categories associated with it.
quantity	number	A positive integer representing the quantity of the SKU purchased.
unitPrice	number	A positive integer representing the unit price of the SKU. The value is blank in case of non-Zippin payment processing.
discountsApplied	array	A list of discount objects representing promotions and loyalty discounts applied to the items in the cart. The object consists of a unique discount code and total amount. The code can be either a Zippin promotion code or a third-party loyalty code.
grossAmount	number	The total amount of all the items purchased, regardless of whether or not payment succeeded, and before discounts and refunds including tax. In the UI, this field is represented as Gross Receipts.
grossTax	number	The applicable tax component of gross receipts.
discount	number	The total discounts applied on purchased items.
loyalty	number	The total loyalty amount applied on purchased items.
taxes	array	The tax applicable to the purchased item. The default value is 0.
grossTaxes	array	The tax applied to the purchased item gross amount. The default value is 0.

The Cart Payment Object

Attribute	Type	Description
paymentAmount	number	The amount charged to the shopper for a transaction.
paymentDate	string	The date on which the payment is done for a transaction. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
paymentReferenceId	string	The Id of the payment gateway or the loyalty charge transaction.
paymentMode	string	The payment method used for this transaction.
last4	string	The card last4 used for this transaction.
brand	string	The card brand used for this transaction.

The Cart Refund Object

Attribute	Type	Description
refundAmount	number	The items returned before the payment is submitted or failed payments, thus reducing the shopper's payment, or after the shopper has paid. This can be items returned and amount both. In the UI, this field is represented as Refunds.
refundDate	string	The date on which the refund is done. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
refundReferenceId	string	The Id of the payment gateway or the loyalty refund transaction.
refundBackToCard	number	The amount of money refunded to a shopper's credit card after the shopper has made the payment. The value may be zero or less if the cart has declined payments.
refundItems	array	A list of refunded items object. The object contains SKU code and quantity.
paymentMode	string	The payment method used for this transaction.
last4	string	The card last4 used for this transaction.
brand	string	The card brand used for this transaction.

Carts

curl -X GET \
  "https://api.getzippin.com/api/carts?startTime=2022-06-01 00:00:00&endTime=2022-06-01 23:59:59&stores=lowceil&limit=10&offset=0&lookup_by=visit_date" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json"

{
  "carts": [
    {
      "cartId": "6feba34d-7242-489e-8357-1634007d4b20",
      "userToken": "fb9afe2b-d22b-4903-8e66-c73745aa69a9",
      "items": [
        {
          "unitPrice": 0.9,
          "discountsApplied": [
            {
              "code": "Broncos - 20% off Concessions",
              "amount": 0.9
            }
          ],
          "quantity": 5,
          "sku": "DTSNPLPCH",
          "name": "Diet Snapple Peach Tea, 20 fl oz",
          "categories": [
            {
              "code": "beernmore",
              "name": "Beer"
            }
          ],
          "grossAmount": 4.89,
          "grossTax": 0.39,
          "discount": 0,
          "loyalty": 0.9,
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "percentage",
              "sales_tax": 8.5679
            }
          ],
          "grossTaxes": [
            {
              "sales_tax": 0.39,
              "name": "Sales Tax"
            }
          ],
          "gratuity": 0
        },
        {
          "unitPrice": 50.01,
          "discountsApplied": [
            {
              "code": "Broncos - 20% off Concessions",
              "amount": 10
            }
          ],
          "quantity": 1,
          "sku": "GATORTEST",
          "name": "gator1",
          "categories": [
            {
              "code": "drinks",
              "name": "Drinks"
            }
          ],
          "grossAmount": 50.01,
          "grossTax": 0,
          "discount": 0,
          "loyalty": 10,
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "percentage",
              "sales_tax": 0
            }
          ],
          "grossTaxes": [
            {
              "sales_tax": 0,
              "name": "Sales Tax"
            }
          ],
          "gratuity": 0.1
        }
      ],
      "status": "paid",
      "storeId": "lowceil",
      "timezone": "America/Los_Angeles",
      "entryTimestamp": "2022-09-14T01:30:00.000-07:00",
      "exitTimestamp": "2022-09-14T01:35:00.000-07:00",
      "processedDate": "2022-09-14T03:37:53.000-07:00",
      "totalItems": 6,
      "updatedAt": 1663299629,
      "loyalty": 10.9,
      "loyaltyMembership": {"id":["gwztop","jmDtkY"],"provider":"lava"},
      "grossAmount": 54.9,
      "grossTax": 0.39,
      "grossTaxes": [
        {
          "sales_tax": 0.39,
          "name": "Sales Tax"
        }
      ],
      "receivedTaxes": [
        {
          "sales_tax": 0.19,
          "name": "Sales Tax"
        }
      ],
      "discount": 0,
      "pendingAmount": 0,
      "refundAmount": 1.56,
      "refundBackToCard": 0,
      "receivedAmount": 42.36,
      "receivedTax": 0.19,
      "gratuity": 0.1,
      "receivedGratuity": 0.1,
      "paymentGatewayName": "freedompay",
      "errorCode": "",
      "errorMessage": "",
      "underReview": 0,
      "isOfflineTransaction": false,
      "payments": [
        {
          "paymentAmount": 42.36,
          "paymentDate": "2022-09-14T03:40:00.000-07:00",
          "paymentReferenceId": "89992592779951686497",
          "paymentMode": "Credit/debit card",
          "last4": "1003",
          "brand": "VISA"
        }
      ],
      "refunds": [
        {
          "refundAmount": 1.56,
          "refundDate": "2022-09-14T05:00:00.000-07:00",
          "refundItems": [
            {
              "sku": "DTSNPLPCH",
              "quantity": 2
            }
          ],
          "refundReferenceId": "c8d9c470-9cb7-4619-b165-8aa617a0ab83",
          "refundBackToCard": 0,
          "paymentMode": "Credit/debit card",
          "last4": "1003",
          "brand": "VISA"
        }
      ]
    }
    ...
    ...
  ],
  "totalRecords": 24,
  "fetchedRecords": 24,
  "currency": "USD"
}

This API returns all the eligible carts for selected stores or intervals.

Request

URL

GET https://api.getzippin.com/api/carts?startTime=2022-06-01 00:00:00&endTime=2022-06-01 23:59:59&stores=lowceil&limit=10&offset=0&lookup_by=visit_date

Request Attributes

Attribute	Type	Description
startTime	DateTime	Date and time of shopper entry/transaction in YYYY-MM-DD HH:MM:SS format. Timing is optional. The default time is 00:00:00.
endTime	DateTime	Date and time of shopper exit/transaction in YYYY-MM-DD HH:MM:SS format. Timing is optional. The default time is 23:59:59.
stores	string	Comma-separated string with retailer store IDs.
limit	number	Limit the number of records to be returned. The default value is 100.
offset	number	Offset is the starting record ID to return the list of records. The default value is 0.
lookup_by	string	(Optional) Possible values: visit_date transaction_date By default, data is retrieved based on visit date and time. Set this attribute to transaction_date when you want to pull data based on transaction date and time.

Response

An associative array with the Cart object containing an array of carts limited to 100, starting after cart offset. Each entry in the array is a separate cart object. If there are no further carts available, the resulting array is blank. There are no errors displayed after the request is sent.

Response Attributes

Attribute	Type	Description
carts	array	The eligible cart object for the given parameters.
totalRecords	number	The total number of carts eligible for the given parameters.
fetchedRecords	number	The total number of carts that are fetched (out of totalRecords) after considering offset and limit.
currency	string	The common currency code of all the supplied stores. Three-letter ISO currency code, in lowercase.

Carts Summary

curl -X GET \
  "https://api.getzippin.com/api/carts/summary?startTime=2022-06-01 00:00:00&endTime=2022-06-01 23:59:59&stores=lowceil&lookup_by=visit_date" \
  -H "Authorization: Bearer test_54032af3-6864-4210-8cb9-423d7273577d" \
  -H "Content-Type: application/json"

{
  "totalOrders": 24,
  "totalCarts": 24,
  "processedCarts": 24,
  "totalItems": 72,
  "grossReceipts": "1311.87",
  "grossTax": "2.07",
  "grossTaxes": [
    {
      "sales_tax": 2.07,
      "name": "Sales Tax"
    }
  ],
  "discount": "90.24",
  "loyalty": "89.73",
  "declinedPayments": "441.31",
  "refunds": "396.91",
  "receivedAmount": "293.26",
  "receivedTax": "0.72",
  "receivedTaxes": [
    {
      "sales_tax": 0.72,
      "name": "Sales Tax"
    }
  ],
  "refundBackToCard": "117.77",
  "creditCardShoppers": 22,
  "appShoppers": 0,
  "totalShoppers": 26,
  "processedShoppers": 24,
  "averageShoppingTime": 288,
  "conversionRate": 100,
  "topSellingItems": [
    {
      "sku": "DTSNPLPCH",
      "name": "Diet Snapple Peach Tea, 20 fl oz",
      "count": 27,
      "receipts": "26.37"
    },
    {
      "sku": "GATORTEST",
      "name": "gator1",
      "count": 15,
      "receipts": "700.14"
    },
    {
      "sku": "WTPSTMUG",
      "name": "White Plastic Mug, Generic",
      "count": 21,
      "receipts": "90.00"
    },
    {
      "sku": "CALIBSKU",
      "name": "Calibration Sku",
      "count": 9,
      "receipts": "495.36"
    }
  ],
  "topSellingCategories": [
    {
      "category": "Beer",
      "count": 27,
      "receipts": "26.37"
    },
    {
      "category": "Drinks",
      "count": 15,
      "receipts": "700.14"
    },
    {
      "category": "Miscellaneous",
      "count": 30,
      "receipts": "585.36"
    }
  ],
  "groupedGrossSales": {
    "9": 277.03,
    "10": 0,
    "11": 912.11,
    "12": 0,
    "13": 0,
    "14": 122.73
  },
  "averageCartSize": "59.63",
  "estimatedGrossReceipts": "1431.13",
  "averageItemsPerCart": "3.00",
  "repeatShoppers": 12,
  "underReview": 0,
  "currency": "USD",
  "currencySymbol": "$"
}

This API returns a summary of all the eligible carts for selected stores or intervals.

Request

URL

GET https://api.getzippin.com/api/carts/summary?startTime=2022-06-01 00:00:00&endTime=2022-06-01 23:59:59&stores=lowceil&lookup_by=visit_date

Request Attributes

Attribute	Type	Description
startTime	DateTime	Date and time of shopper entry/transaction in YYYY-MM-DD HH:MM:SS format. Timing is optional. The default time is 00:00:00.
endTime	DateTime	Date and time of shopper exit/transaction in YYYY-MM-DD HH:MM:SS format. Timing is optional. The default time is 23:59:59.
stores	string	Comma-separated string with retailer store IDs.
lookup_by	string	(Optional) Possible values: visit_date transaction_date By default, data is retrieved based on visit date and time. Set this attribute to transaction_date when you want to pull data based on transaction date and time.

Response

A summary of all the eligible carts is returned for selected stores. If any of the selected stores have more than one currency, there will be no valid data.

Response Attributes

Attribute	Type	Description
totalOrders	number	The number of shopper groups who purchased items in the store. Each shopper group is one or more individuals who entered the store at the same time using a single credit card.
totalCarts	number	The number of shopper groups who entered the store. Each shopper group is one or more individuals who entered the store at the same time using a single credit card.
processedCarts	number	Number of carts processed.
totalItems	number	The total quantity of items purchased across all carts.
grossReceipts	number	The total amount of all the items purchased, regardless of whether or not payment succeeded, and before discounts and refunds including tax.
grossTax	number	The applicable tax component of gross receipts.
grossTaxes	array	The applicable tax component of gross receipts at tax type level.
discount	number	The total discounts applied on purchased items.
loyalty	number	The total loyalty amount applied on purchased items.
declinedPayments	number	The total amount submitted to the payment gateway or processor that was declined. Partial or the total amount may be automatically resubmitted after a short period of time and subsequently be approved.
refunds	number	The items returned before the payment is submitted or failed payments, thus reducing the shopper's payment, or after the shopper has paid. This can be items returned and amount both.
receivedAmount	number	The net amount received after deducting discounts, loyalty, declined payments, and refunds, then adding received tax.
receivedTax	number	This is the tax component of the received amount.
receivedTaxes	array	The tax component of the received amount at tax type level.
refundBackToCard	number	The amount of money refunded to a shopper's credit card after the shopper has made the payment. This amount can be less than the Refunds. The value may be zero or less if the cart has declined payments.
creditCardShoppers	number	Credit card displays the number of shoppers shopping in the store by using either a physical credit card or a third-party payment app such as Apple Pay or Google Pay.
appShoppers	number	App is the number of shopper parties shopping in the store using Zippin’s Shopper App.
totalShoppers	number	The number of shoppers entered in a store at a selected time.
processedShoppers	number	The number of shoppers processed is the number of individuals in all groups exiting the store whose virtual shopping carts have been completed. This shows how close Zippin is to completing invoices for the event or day.
averageShoppingTime	number	The mean number of seconds between an individual shopper entering the store through the entry turnstile and exiting the store through the exit turnstile.
conversionRate	number	The percentage of all shoppers who actually made purchases in the store. In case of group shopping, the system considers as a single shopper. This rate is derived from total number of orders against total number of carts.
topSellingItems	array	The product wise number of items sold and their sales amount.
topSellingCategories	array	The category wise number of items sold and their sales amount.
groupedGrossSales	array	Gross receipts for the given intervals.
averageItemsPerCart	number	The mean number of items per cart with purchases.
averageCartSize	number	The mean amount of gross receipts per cart with purchases.
repeatShoppers	number	The number of repeat shoppers who return to the store multiple times for more shopping. Typically, a repeat shopper has made at least two purchases from the store.
estimatedGrossReceipts	number	The number of individuals who have entered the store multiplied by the conversion rate (from individual entering the store to purchasing) multiplied by the average spend per individual purchasing. This estimate is generated once we have processed enough data to be confident that it will be very close to the final gross receipts amount.
underReview	number	The total amount that is under review when processing the dispute request.
currency	string	The common currency code of all the supplied stores. Three-letter ISO currency code, in lowercase.
currencySymbol	string	The common currency symbol of all the supplied stores.

Here are few scenarios of responses when the API is called:

Scenario 1:

startTime = 2022-09-01 and endTime = 2022-09-01

This API returns all shopper carts created between 2022-09-01 00:00:00 and 2022-09-01 23:59:59.

Shopper entry time = 2022-09-01 20:00:00
Cart Id 1 finalized time = 2022-09-01 22:00:00
Billed time = 2022-09-01 22:30:00
Purchased amount = 50 and successfully billed entire amount

The API response returns the above Cart Id 1 with 50 in the received amount and 0 in the pending amount.

Scenario 2:

startTime = 2022-09-02 and endTime = 2022-09-02

This API returns all shopper carts created between 2022-09-02 00:00:00 and 2022-09-02 23:59:59.

Shopper entry time = 2022-09-02 23:00:00
Cart Id 2 finalized time = 2022-09-02 23:59:00
Billing not completed for the day or payment failed for the entire amount

The API response returns the above Cart Id 2 with 0 in the received amount and 50 in the pending amount.

startTime = 2022-09-03 and endTime = 2022-09-03

This API returns all shopper carts created between 2022-09-03 00:00:00 and 2022-09-03 23:59:59.

Cart Id 2 billed time or retried time = 2022-09-03 00:30:00 and successfully billed the entire amount.
New shopper entry time = 2022-09-03 20:00:00
Cart Id 3 finalized time = 2022-09-03 22:00:00
Billed time = 2022-09-03 22:30:00
Purchased amount = 50 and successfully billed entire amount

The API response returns the above Cart Id 3 with 50 in the received amount and 0 in the pending amount. It will not return the previous day (2022-09-02) Cart Id 2 that is billed today.

Scenario 3:

startTime = 2022-09-04 and endTime = 2022-09-04

This API returns all shopper carts created between 2022-09-04 00:00:00 and 2022-09-04 23:59:59.

Cart Id 1 refunded time = 2022-09-04 10:30:00 and successfully refunded the full amount.
New shopper entry time = 2022-09-04 20:00:00
Cart Id 4 finalized time = 2022-09-04 22:00:00
Billed time = 2022-09-04 22:30:00
Purchased amount = 50 and successfully billed entire amount

The API response returns the above Cart Id 4 with 50 in the received amount and 0 in the pending amount. It will not return the 2022-09-01 Cart Id 1 that is refunded today.

System

Time Synchronization

This is achievable using standard NTP synchronization and is critical to accurately perform sensor fusion using all available event data. The system is required to use our internal NTP server (if possible) for synchronization to minimize any external disruptions and better synchronize the system as a whole. And if the internal store NTP server is not available, use the most accurate public time source available.

Some Public NTP Services
- Google's NTP Service. (Google)
- NIST’s NTP Service (time.nist.gov)

Events

curl -X POST \
  "http://zippin-gateway/api/v1/events/" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{ 
    "type": "person-access",
    "sent_ts": 1689172938810,
    "store_id": "store123",
    "source": "qr11",
    "start": 1689172938799, 
    "end": 1689172938805,
    "attributes": [{
      "user_token": "aW0gYSBsaXR0bGUgdGVhcIHNob3J0IGFuZCBzdG91dA",
      "decision": "ALLOW",
      "payment_method": "chip",
      "payment_type": "credit",
      "card_brand": "VISA",
      "card_last4" : "1005",
      "card_expiry_date" : "02/24",
    }],
    "provider_id": "payment_partner_xyz",
    "provider_data": {"membership_id": "DFoLhapMRK2RRafSogLHMQ"}
  }'

200 OK

{ 
  "id": "7955a66c-2738-4662-a4c4-e08e8beaf332",
  "type": "person-access",
  "sent_ts": 1689172938810,
  "store_id": "store123",
  "source": "qr11",
  "start": 1689172938799, 
  "end": 1689172938805,
  "attributes": [{
    "user_token": "aW0gYSBsaXR0bGUgdGVhcIHNob3J0IGFuZCBzdG91dA",
    "decision": "ALLOW"
    "payment_method": "chip",
    "payment_type": "credit",
    "card_brand": "VISA",
    "card_last4" : "1005",
    "card_expiry_date" : "02/24",
  }],
  "provider_id": "payment_partner_xyz",
  "provider_data": {"membership_id": "DFoLhapMRK2RRafSogLHMQ"}
}

The Events API allows the integration partner to send events to the Zippin system. This is a generic API to support multiple use-cases such as entry check-in, IOT dispensing systems, made to order, and more.

The Events object represents a customer interaction with the store system. For example, an event that the shopper scanned a credit card before entering the store.

Request

URL

POST http://zippin-gateway/api/v1/events/

Request Attributes

Attribute	Required?	Type	Description
type	yes	string	Event type to identify different interactions such as `person-access` for entry check-in; and `items-purchased` for a coffee dispensing machine.
sent_ts	yes	int	Message send time in milliseconds since the epoch. This is the time when this message was sent from the client. This is useful in terms of measuring clock skew between the client and the server.
store_id	yes	string	The identifier of the store.
source	yes	string	Source for the event. For example, for `person-access` event, `source` identifies the entrance that should be opened to let the shopper enter the store.
start	yes	int	Event start timestamp in milliseconds since the epoch. For `person-access` event, `start` is when the shopper starts scanning the card.
end	yes	int	Event end timestamp in milliseconds since the epoch. For `person-access` event, `end` is when the shopper is authorized to enter.
attributes	yes	array	An array of event-specific JSON objects. See Event Specific Attributes.
provider_id	optional	string	Identifier of the Payment Partner as configured during the setup process.
provider_data	optional	JSON	Additional integration specific data. `provider_id` is required when sending any data in `provider_data`.

Response

Returns the request payload on success or an error on failure.

Response Attributes

Attribute	Required?	Type	Description
id	generated	uuid4	Unique identifier for this event. This is auto-generated.
type	yes	string	Event type to identify different interactions such as `person-access` for entry check-in; and `items-purchased` for a coffee dispensing machine.
sent_ts	yes	int	Message send time in milliseconds since the epoch. This is the time when this message was sent from the client. This is useful in terms of measuring clock skew between the client and the server.
store_id	yes	string	The identifier of the store.
source	yes	string	Source for the event. For example, for `person-access` event, `source` identifies the entrance that should be opened to let the shopper enter the store.
start	yes	int	Event start timestamp in milliseconds since the epoch. For `person-access` event, `start` is when the shopper starts scanning the card.
end	yes	int	Event end timestamp in milliseconds since the epoch. For `person-access` event, `end` is when the shopper is authorized to enter.
attributes	yes	array	An array of event-specific JSON objects. See Event Specific Attributes.
provider_id	optional	string	Identifier of the Payment Partner as configured during the setup process.
provider_data	optional	JSON	Additional integration specific data. `provider_id` is required when sending any data in `provider_data`.

Event Specific Attributes

person-access

Attribute	Required?	Type	Description
user_token	yes	string (uuid4 or a similar string)	Identifies the user entering the store. It is recommended, however not required, to send the same token every time the same user enters the store, or the same card is scanned.
decision	yes	string	One of the following values: `ALLOW` - The shopper is authorized for shopping. `DENY` - The shopper is not authorized for shopping. Payments Partner can decide to not integrate the `DENY` option.
decline_reason	optional	string	Reason for `DENY` decision. Payments Partner can decide to not integrate the `DENY` option.
payment_method	optional	string	The mode of entry. For example, swipe, tap, or more.
payment_type	optional	string	The type of payment, whether credit or debit.
card_brand	optional	string	The card network of the card the shopper used for shopping. For example, VISA, Mastercard, and more.
card_last4	yes	string	The last four digits of the card. This is required for the receipt microsite where Zippin is responsible for billing.
card_expiry_date	yes	string	The expiry date of the card.

Configuration

curl -X GET \
  "http://zippin-gateway/api/v1/configs?store_id=<store_id>&system_id=<system-id>" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json"

200 OK

{
  "store_id": "store123",
  "system_id": "tr03",
  "store_status": "UP",
  "updated_ts": 1689172938810,
  "configuration": {
    "config_version": "3.1.2",
  }
}

The purpose of using this API is twofold:

For the connector to pull the latest configuration parameters.
To fetch the state of the store. For example, Store Up, Store Down, Store Maintenance, or Crew Only.

It is beneficial especially to fetch the state of the store to turn on or off different systems. For example, if the store is in down mode, the Payments Partner can show relevant message on their device to let the customers know that the store is closed for shopping.

If implemented this API must be called at the start of the connector service. Device configuration is usually needed to setup devices to operate properly.

If this API is not implemented, configuration parameters can be configured manually and not by fetching through this API, thus ignoring the state of the store.

Request

URL

GET http://zippin-gateway/api/v1/configs?store_id=<store_id>&system_id=<system-id>

Parameter	Required?	Type	Description
store_id	yes	string	The identifier of the store.
system_id	yes	string	Target system for this configuration. The configuration is coming from the cloud specific for this system.

Response

Returns the latest configuration.

Response Attributes

Attribute	Required?	Type	Description
store_id	yes	string	The identifier of the store.
store_status	yes	string, enum	The current store mode. Valid values are: `UP` - Store is running normally. `MAINTENANCE` - Store is in maintenance mode. `DOWN` - Store is currently down.
system_id	yes	string	Target system for this configuration. The configuration is coming from the cloud specific for this system.
updated_ts	yes	int	Timestamp indicating when the data was last updated. UTC in ms since epoch.
configuration	yes	JSON	The configuration data specific to a particular device.

Metrics

curl -X POST \
  "https://zippin-gateway/api/v1/metrics/" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{ 
    "sent_ts": 1689172938810,
    "store_id": "store123",
    "source": "qr11",
    "metrics": [{
      "heartbeat": {"ts": 1689172938810, "value": 0}
    }]
  }'

200 OK

{ 
  "id": "7955a66c-2738-4662-a4c4-e08e8beaf332",
  "sent_ts": 1689172938810,
  "store_id": "store123",
  "source": "qr11",
  "metrics": [{
    "heartbeat": {"ts": 1689172938810, "value": 0}
  }]
}

This is an object that represents information useful for monitoring the health, function, and performance of a subsystem of a store. These are metrics that enable Zippin to determine if a subsystem is working properly or is in the need of debugging and maintenance. For Payments Partner, this includes the health metrics for the card readers at the store entrance.

Request

URL

POST https://zippin-gateway/api/v1/metrics/

Request Attributes

Attribute	Required?	Type	Description
sent_ts	yes	int	This is the time when this message was sent from the client. Time in milliseconds since the epoch.
store_id	yes	string	Zippin store identifier.
source	yes	string	Uniquely identify the source system sending these metrics. For example, the card reader at the entrance.
metrics	yes	JSON Array	Array of key-value pairs where key is the metric name and value is an array of data-points - each with value, ts, and labels. Metric content details: `value` - A float64 value. Allowed values: `0` - OK and running normally `Non-0` - System is not ok and requires attention. This value is used to help determine the problem. `ts` - A millisecond-precision timestamp. `labels` - (Optional) Do not use labels to store dimensions with high cardinality (many different label values), such as user IDs, email addresses, or other unbounded sets of values.

Response

Returns the request payload on success or an error on failure.

Response Attributes

Attribute	Required?	Type	Description
id	generated	uuid4	Unique identifier for this metric.
sent_ts	yes	int	This is the time when this message was sent from the client. Time in milliseconds since the epoch.
store_id	yes	string	Zippin store identifier.
source	yes	string	Uniquely identify the source system sending these metrics. For example, the card reader at the entrance.
metrics	yes	JSON Array	Array of key-value pairs where key is the metric name and value is an array of data-points - each with value, ts, and labels. Metric content details: `value` - A float64 value. Allowed values: `0` - OK and running normally `Non-0` - System is not ok and requires attention. This value is used to help determine the problem. `ts` - A millisecond-precision timestamp. `labels` - (Optional) Do not use labels to store dimensions with high cardinality (many different label values), such as user IDs, email addresses, or other unbounded sets of values.

Retailer/Partner APIs

You will implement these APIs and provide endpoints to 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": 1552088597,
    "cartId": "o-0e674fdf-f27e-4a39-9c3d-46ec59a361df",
    "items": [
        {
            "sku": "FAY010008147",
            "quantity": 1
        },
        {
            "sku": "789CXP008147",
            "quantity": 2
        }
    ],
    "shoppers": [
      {
         "entryTimestamp":1552088527,
         "exitTimestamp":1552088587,
         "id":"0e674fdf-f27e-4a39-9c3d-46ec59a361df"
      },
      {
         "entryTimestamp":1552088557,
         "exitTimestamp":1552088597,
         "id":"44b28bd9-0b51-4d3b-a4b5-1aa6acf750f1"
      }
    ]
    "updatedAt": 1607581491,
    "corrected": true,
    "disputes": [
      {
        "id": 1607581491_789CXP008147,
        "sku": "789CXP008147",
        "quantity": 1,
        "action": "remove",
        "description": "I took only one item",
        "status": "approved",
        "review_notes": "Billing error, dispute approved"
      },
      {
        "id": 1607581703_FAY010008147,
        "sku": "FAY010008147",
        "quantity": 1,
        "action": "add",
        "description": "I took two of this item",
        "status": "approved",
        "review_notes": "Billing error, dispute approved"
      }
    ]
  }'

{
  "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.

If group shopping is enabled, there is one cart for whole group. This means there is only 1 cart submission with all the products shopped by the group. Group shopping may also be be referred as Family shopping. Entry and Exit notifications are sent for individual shoppers in the group.

If group shopping is not enabled, then each shopper has 1 cart. This means a cart is submitted for each shopper.

Corrected cart

When you get a dispute request, you can use our Dispute API or the orders dashboard to submit with requested details to help us resolve the dispute. The dispute request can be approved in case identified any discrepancy or rejected if not.

The given dispute quantity will be added to the item if the dispute action is "add" (under-billed) and the given dispute quantity will be reduced from the item if the dispute action is "remove" (over-billed) only for the approved dispute request.

This API will be called with corrected items, corrected flag = true and dispute request details when we resolve the dispute. This API will be called with dispute details even though all the dispute requests are rejected.

The corrected flag will be false and there is no dispute attribute in case there is no dispute for a cart.

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 shopper. Measured in seconds since the Unix epoch.
exitTimestamp	timestamp	Exit time of the shopper. 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.
shoppers	array	An array of shoppers associated with the cart. If group shopping is enabled, there may be multiple shoppers for same cart. Otherwise, there is only 1 shopper for the cart.
updatedAt	timestamp	Timestamp when cart was updated. Measured in seconds since the Unix epoch.
corrected	"true" or "false"	This flag will be true when there is a dispute request for the cart else false.
disputes	array	An array of dispute object in the cart. This will be empty when cart does not have any disputes.

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. Entry and Exit notifications are sent for individual shoppers in the group.

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.

QR Code Validation

curl -X POST \
  "https://api.retailer.example.com/v1/authorizations" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "store123",
    "entranceId": "qr11",
    "code": "123456789",
    "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999"
  }'

200 OK

{
  "decision": "allow", // or "deny"
  "userToken": "9fabb8f0-2de1-4b75-9d3c-d5ddc1467999",
  "decline_reason": "insufficient balance"
}

This API applies when you generate the QR code but not in Zippin specified format. In this case, Zippin is unable to verify the QR code when the shopper scans the QR code, instead the Zippin Access Service reads the QR code and calls your Authorizations REST API for QR code validation. This API returns an Allow or Deny response.

Request

URL

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

Request Attributes

Attribute	Type	Description
storeId	string	Required. The identifier of the store. This is configured in Zippin system during the store set-up.
entranceId	string	Required. The identifier of the gate/turnstile/location where the QR code was scanned.
code	string	Required. Scanned QR code.
userToken	string	The identifier of the user generated by Zippin.

Response

Returns the success or failure status code.

Response Attributes

Attribute	Type	Description
decision	string	Required. Valid values are "allow" or "deny". If the decision is "allow", the gate opens allowing the shopper to enter. If the decision is "deny", your app must notify the shopper about the reason for not allowing entry to the store.
userToken	string	Required. The identifier of the user. Return the user token sent in request or overwrite what you generated. This user token will be used for identifying the user.
decline_reason	string	Optional. Reason for decline.

Webhook/Push Transactions

curl -X POST \
  "https://api.retailer.example.com/v1/transactions" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
      "cartId": "6feba34d-7242-489e-8357-1634007d4b20",
      "userToken": "fb9afe2b-d22b-4903-8e66-c73745aa69a9",
      "items": [
        {
          "unitPrice": 0.9,
          "discountsApplied": [
            {
              "code": "Broncos - 20% off Concessions",
              "amount": 0.9
            }
          ],
          "quantity": 5,
          "sku": "DTSNPLPCH",
          "name": "Diet Snapple Peach Tea, 20 fl oz",
          "categories": [
            {
              "code": "beernmore",
              "name": "Beer"
            }
          ],
          "grossAmount": 4.89,
          "grossTax": 0.39,
          "discount": 0,
          "loyalty": 0.9,
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "percentage",
              "sales_tax": 8.5679
            }
          ],
          "grossTaxes": [
            {
              "sales_tax": 0.39,
              "name": "Sales Tax"
            }
          ],
          "gratuity": 0
        },
        {
          "unitPrice": 50.01,
          "discountsApplied": [
            {
              "code": "Broncos - 20% off Concessions",
              "amount": 10
            }
          ],
          "quantity": 1,
          "sku": "GATORTEST",
          "name": "gator1",
          "categories": [
            {
              "code": "drinks",
              "name": "Drinks"
            }
          ],
          "grossAmount": 50.01,
          "grossTax": 0,
          "discount": 0,
          "loyalty": 10,
          "taxes": [
            {
              "name": "Sales Tax",
              "type": "percentage",
              "sales_tax": 0
            }
          ],
          "grossTaxes": [
            {
              "sales_tax": 0,
              "name": "Sales Tax"
            }
          ],
          "gratuity": 0.1
        }
      ],
      "status": "paid",
      "storeId": "lowceil",
      "timezone": "America/Los_Angeles",
      "entryTimestamp": "2022-09-14T01:30:00.000-07:00",
      "exitTimestamp": "2022-09-14T01:35:00.000-07:00",
      "processedDate": "2022-09-14T03:37:53.000-07:00",
      "totalItems": 6,
      "updatedAt": 1663299629,
      "loyalty": 10.9,
      "loyaltyMembership": {"id":["gwztop","jmDtkY"],"provider":"lava"},
      "grossAmount": 54.9,
      "grossTax": 0.39,
      "grossTaxes": [
        {
          "sales_tax": 0.39,
          "name": "Sales Tax"
        }
      ],
      "receivedTaxes": [
        {
          "sales_tax": 0.19,
          "name": "Sales Tax"
        }
      ],
      "discount": 0,
      "declinedAmount": 0,
      "refundAmount": 1.56,
      "refundBackToCard": 0,
      "receivedAmount": 42.36,
      "receivedTax": 0.19,
      "gratuity": 0.1,
      "receivedGratuity": 0.1,
      "paymentGatewayName": "freedompay",
      "errorCode": "",
      "errorMessage": "",
      "payments": [
        {
          "paymentAmount": 42.36,
          "paymentDate": "2022-09-14T03:40:00.000-07:00",
          "paymentReferenceId": "89992592779951686497",
          "paymentMode": "Credit/debit card",
          "last4": "1003",
          "brand": "VISA"
        }
      ],
      "refunds": [
        {
          "refundAmount": 1.56,
          "refundDate": "2022-09-14T05:00:00.000-07:00",
          "refundItems": [
            {
              "sku": "DTSNPLPCH",
              "quantity": 2
            }
          ],
          "refundReferenceId": "c8d9c470-9cb7-4619-b165-8aa617a0ab83",
          "refundBackToCard": 0,
          "paymentMode": "Credit/debit card",
          "last4": "1003",
          "brand": "VISA"
        }
      ],
      "currency":"USD"
    }'

200 OK

This API pushes all transactions of a cart. If the cart is charged through an external billing system, it will only push the cart submission transaction. If the cart is charged through Zippin's billing system, it will push the cart submission, payment and refund transactions.

Request

URL

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

Request Attributes

Attribute	Type	Description
cartId	string	The Zippin cart identifier for a shopping session.
userToken	string	Identifies the user who is responsible for this cart.
items	array	A list of items in the cart. This field is blank in case there are no items in the cart.
status	string	The status of the cart. The status can be `Processed`, `Processing failed`, `Ready for billing`, `failed`, `partial`, `paid`.
storeId	string	The identifier of the retailer store.
timezone	string	The local time zone of the store. For example, "America/Los_Angeles".
entryTimestamp	string	Date and time of the shopper entry. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
exitTimestamp	string	Date and time of the shopper exit. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
processedDate	string	Date and time the cart was processed. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
totalItems	number	The total quantity of items purchased.
updatedAt	number	Timestamp when the cart was last updated. It is measured in seconds from the Unix epoch.
loyaltyMembership	object	Optional. An object containing a list of loyalty IDs and loyalty provider/partner ID of the third party loyalty membership program. In case of group shopping, it is the membership ID of the shopper who is charged. This field is blank when the loyalty membership code is not scanned by the shopper while shopping. This applies only to carts charged using Zippin's billing system.
grossAmount	number	Optional. The total amount of all the items purchased, regardless of whether or not payment succeeded, and before discounts and refunds including tax. In the UI, this field is represented as Gross Receipts. This applies only to carts charged using Zippin's billing system.
grossTax	number	Optional. The applicable tax component of gross receipts. This applies only to carts charged using Zippin's billing system.
grossTaxes	array	Optional. The applicable tax component of gross receipts at tax type level. This applies only to carts charged using Zippin's billing system.
receivedTaxes	array	Optional. The tax component of the received amount at tax type level. This applies only to carts charged using Zippin's billing system.
discount	number	Optional. The total discounts applied on purchased items. This applies only to carts charged using Zippin's billing system.
loyalty	number	Optional. The total loyalty amount applied on purchased items. This applies only to carts charged using Zippin's billing system.
declinedAmount	number	Optional. The total amount submitted to the payment gateway or processor that was declined. Partial or the total amount may be automatically resubmitted after a short period of time and subsequently be approved. In the UI, this field is represented as Declined Payments. This applies only to carts charged using Zippin's billing system.
refundAmount	number	Optional. The items returned before the payment is submitted or failed payments, thus reducing the shopper's payment, or after the shopper has paid. This can be items returned and amount both. In the UI, this field is represented as Refunds. This applies only to carts charged using Zippin's billing system.
refundBackToCard	number	Optional. The amount of money refunded to a shopper's credit card after the shopper has made the payment. The value may be zero or less if the cart has declined payments. This applies only to carts charged using Zippin's billing system.
receivedAmount	number	Optional. The net amount received after deducting discounts, loyalty, declined payments, and refunds, then adding received tax. This applies only to carts charged using Zippin's billing system.
receivedTax	number	Optional. The tax component of the received amount. This applies only to carts charged using Zippin's billing system.
gratuity	number	Optional. The applicable gratuity component of gross receipts. This applies only to carts charged using Zippin's billing system.
receivedGratuity	number	Optional. The gratuity component of the received amount. This applies only to carts charged using Zippin's billing system.
paymentGatewayName	string	Optional. The name of the payment gateway used to charge a cart. This applies only to carts charged using Zippin's billing system.
errorCode	string	The error code from the payment gateway for a failed payment of a cart.
errorMessage	string	The error message from the payment gateway for a failed payment of a cart.
payments	array	Optional. A list of payment objects. This applies only to carts charged using Zippin's billing system.
refunds	array	Optional. A list of refunds objects. This applies only to carts charged using Zippin's billing system.
currency	string	Optional. The common currency code of all the supplied stores. Three-letter ISO currency code, in lowercase. This applies only to carts charged using Zippin's billing system.

The Cart Item Object

Attribute	Type	Description
sku	string	The unique ID of the SKU (stock keeping units) that identifies an item in the cart.
name	string	The name of the SKU.
categories	array	A list of category objects. A single SKU can have multiple categories associated with it.
quantity	number	A positive integer representing the quantity of the SKU purchased.
unitPrice	number	A positive integer representing the unit price of the SKU. The value is blank in case of non-Zippin payment processing.
discountsApplied	array	A list of discount objects representing promotions and loyalty discounts applied to the items in the cart. The object consists of a unique discount code and total amount. The code can be either a Zippin promotion code or a third-party loyalty code.
grossAmount	number	The total amount of all the items purchased, regardless of whether or not payment succeeded, and before discounts and refunds including tax. In the UI, this field is represented as Gross Receipts.
grossTax	number	The applicable tax component of gross receipts.
gratuity	number	Optional. The applicable gratuity component of gross receipts.
discount	number	The total discounts applied on purchased items.
loyalty	number	The total loyalty amount applied on purchased items.
taxes	array	The tax applicable to the purchased item. The default value is 0.
grossTaxes	array	The tax applied to the purchased item gross amount. The default value is 0.

The Cart Payment Object

Attribute	Type	Description
paymentAmount	number	The amount charged to the shopper for the transaction.
paymentDate	string	The date on which the payment is done for the transaction. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
paymentReferenceId	string	The Id of the payment gateway or the loyalty charge transaction.
paymentMode	string	The payment method used for this transaction.
last4	string	The card last4 used for this transaction.
brand	string	The card brand used for this transaction.

The Cart Refund Object

Attribute	Type	Description
refundAmount	number	The items returned before the payment is submitted or failed payments, thus reducing the shopper's payment, or after the shopper has paid. This can be items returned and amount both. In the UI, this field is represented as Refunds.
refundDate	string	The date on which the refund is done. It is displayed in ISO 8601 local date and time format, including time zone offset. For example, yyyy-mm-ddThh:mm:ss.nnn+hh:mm.
refundReferenceId	string	The Id of the payment gateway or the loyalty refund transaction.
refundBackToCard	number	The amount of money refunded to a shopper's credit card after the shopper has made the payment. The value may be zero or less if the cart has declined payments.
refundItems	array	A list of refunded items object. The object contains SKU code and quantity.
paymentMode	string	The payment method used for this transaction.
last4	string	The card last4 used for this transaction.
brand	string	The card brand used for this transaction.

Response

Returns the success or failure HTTP status code.

Transaction delivery behaviors

This section helps you understand different behaviors to expect regarding how Zippin sends transactions to your webhook/push transaction endpoint.

Cart submission behavior

curl -X POST \
  "https://api.retailer.example.com/v1/transactions" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "6feba34d-7242-489e-8357-1634007d4b20",
    "userToken": "fb9afe2b-d22b-4903-8e66-c73745aa69a9",
    "items": [
      {
        "unitPrice": 0.9,
        "discountsApplied": [
          {
            "code": "Broncos - 20% off Concessions",
            "amount": 0.9
          }
        ],
        "quantity": 5,
        "sku": "DTSNPLPCH",
        "name": "Diet Snapple Peach Tea, 20 fl oz",
        "categories": [
          {
            "code": "beernmore",
            "name": "Beer"
          }
        ],
        "grossAmount": 0,
        "grossTax": 0,
        "discount": 0,
        "loyalty": 0,
        "taxRate": 0,
        "taxes": [],
        "grossTaxes": [],
        "gratuity": 0
      },
      {
        "unitPrice": 50.01,
        "discountsApplied": [
          {
            "code": "Broncos - 20% off Concessions",
            "amount": 10
          }
        ],
        "quantity": 1,
        "sku": "GATORTEST",
        "name": "gator1",
        "categories": [
          {
            "code": "drinks",
            "name": "Drinks"
          }
        ],
        "grossAmount": 0,
        "grossTax": 0,
        "discount": 0,
        "loyalty": 0,
        "taxRate": 0,
        "taxes": [],
        "grossTaxes": [],
        "gratuity": 0
      }
    ],
    "status": "Processed",
    "storeId": "lowceil",
    "timezone": "America/Los_Angeles",
    "entryTimestamp": "2022-09-14T01:30:00.000-07:00",
    "exitTimestamp": "2022-09-14T01:35:00.000-07:00",
    "processedDate": "2022-09-14T03:37:53.000-07:00",
    "updatedAt": 1663299629,
    "totalItems": 6,
    "loyaltyMembership": {},
    "grossAmount": 0,
    "grossTax": 0,
    "grossTaxes": [],
    "receivedTaxes": [],
    "gratuity": 0,
    "receivedGratuity": 0,
    "discount": 0,
    "loyalty": 0,
    "declinedAmount": 0,
    "refundAmount": 0,
    "refundBackToCard": 0,
    "receivedAmount": 0,
    "receivedTax": 0,
    "paymentGatewayName": "",
    "errorCode": "",
    "errorMessage": "",
    "payments": [],
    "refunds": [],
    "currency": "USD"
  }'

When the cart is submitted to the payment system for billing, Zippin sends the transaction details without financial data, such as gross amount, received amount, payments, and refunds etc. You still get those attributes but the value can be 0 or empty.

Processed

A processed status is sent when the cart is successfully submitted to the payment system for billing.

Processing failed

When the cart is submitted to the payment system for billing, if the cart submission fails, a Processing failed status is sent with an errorCode and errorMessage. The same items or updated items will be pushed when the cart is successfully resubmitted.

Empty cart

The payload is pushed with empty array items ("items": []) when the shopper has not purchased anything.

Payment behavior

After processing the payment, Zippin sends transaction details along with financial data such as total amount, received amount, payments and refunds etc. Payment status can be failed, partial or paid. Failure to pay the full cart amount will result in failed status. If only part of the cart amount is charged it will result in partial status. If the full cart amount is charged it will result in paid status.

Refund behavior

After processing the dispute request, Zippin sends the transaction details along with financial data such as total amount, received amount, payments and refunds etc.

You will get a status of Ready for Billing when the dispute is processed before processing the payment.

You will get a status of failed, partial or paid when the dispute is processed after processing the payment.

Retry behavior

Payment is retried in case of failed or partial status. Zippin sends transaction details along with financial data such as total amount, received amount, payments and refunds etc only when the payment is successful.

Loyalty ID

curl -X POST \
  "https://api.partner.com/v1/loyaltyid" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "store123",
    "code": "q2Q4NqIKDmsKAd9Vsw5hPHB1YKJ95ea8odOroic",
    "scan_timestamp": 1689172938805,
  }'

{
  "loyalty_id": "DFoLhapMRK2RRafSogLHMQ",
  "data": {
    "customer_id": "Q8002FAM9V1EZ0ADB2T5609X6NET1H"
  }
}

Zippin calls the loyalty partner backend to retrieve the long-lived Loyalty ID. If the scanned code itself is long-lived, loyalty partner can skip implementing this API and Zippin will use the scanned code as the loyalty id, otherwise, loyalty partner needs to implement this API endpoint.

Request

URL

POST https://api.partner.com/v1/loyaltyid

Request Attributes

Attribute	Type	Description
store_id	string	The identifier of the store.
code	string	The loyalty code scanned by the shopper.
scan_timestamp	number	Time of loyalty code scan. Measured in milliseconds since the epoch.

Response

Return long-lived loyalty id corresponding to the scanned code.

Response Attributes

Attribute	Type	Description
loyalty_id	string	Long-lived loyalty id corresponding to the scanned code. This can be same as the code if that itself is long-lived.
data	JSON	(Optional) Any other integration data, if needed.

Promotions

curl -X POST \
  "https://api.partner.com/v1/discounts" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "S6241",
    "cart_id": "0e674fdf-f27e-4a39-9c3d-46ec59a361df",
    "user_token": "9fabb8f0-2de1-9d3c-d5ddc1467999",
    "total_amount": 5,
    "currency": "USD",
    "items": [
      {
        "sku": "DTSNLPCH",
        "name": "Diet Snapple",
        "quantity": 1,
        "unit_price": 5,
        "taxes": [
          {
            "sales_tax": 8.5,
            "type": "percentage"
          }
        ]
      }
    ],
    "providers": [
      {
        "id": "partner-xyz",
        "data": {
          "loyalty_id": "DFoLhapMRK2RRafSogLHMQ",
          "data": {
            "customer_id": "Q8002FAM9V1EZ0ADB2T5609X6NET1H"
          }
        }
      },
      {
        "id": "partner-xyz",
        "data": {
          "loyalty_id": "SogLHMQK2RRafDFoLhapMR",
          "data": {
            "customer_id": "ADB2T5609X6NET1HQ8002FAM9V1EZ0"
          }
        }
      }
    ]
  }'

{
  "user_token": "9fabb8f0-2de1-9d3c-d5ddc1467999",
  "transaction_id": "38e07e0e-c90d-47d5-866b-d506a21a4dcb",
  "currency": "USD",
  "discounts": [
    {
      "value": 50,
      "type": "percentage",
      "coupon_code": "50_PERCENT_OFF",
      "description": "50% off"
    }
  ],
  "items": [
    {
      "sku": "DTSNLPCH",
      "discounts": [
        {
          "value": 5,
          "type": "absolute",
          "coupon_code": "1OFF",
          "description": "$5 off"
        }
      ]
    },
    {
      "sku": "COKE",
      "discounts": [
        {
          "value": 20,
          "type": "percentage",
          "coupon_code": "20_PERCENT_OFF",
          "description": "20% off"
        }
      ]
    }
  ]
}

To apply promotions to a cart, Zippin calls the loyalty partner backend in the cloud.

Request

URL

POST https://api.partner.com/v1/discounts

Request Attributes

Attribute	Type	Description
store_id	string	The identifier of the store.
cart_id	string	The identifier of the Zippin cart.
user_token	string	The identifier of the shopper.
total_amount	number	The identifier of the shopper.
currency	string	Transaction currency code in ISO 4217 3 Character Alphabetic Code.
items	array	An array of items (SKU and quantity) in the cart. There must be at least one item in the cart.
providers	array	Array of JSON objects (id, data) containing the identifier of the loyalty partner and all loyalty ids and any other integration data sent to Zippin as part of Loyalty ID API responses.

Response

Returns the applied discount details.

Response Attributes

Attribute	Type	Description
cart_id	string	(Optional) The identifier of the Zippin cart.
user_token	string	(Optional) The identifier of the shopper.
transaction_id	string	(Optional) The identifier of the transaction.
currency	string	(Optional) Transaction currency code in ISO 4217 3 Character Alphabetic Code.
discounts	array	Discount applied on an item or at the cart level or both.
items	array	An array of items (SKU, name, quantity, discounts) in the cart.

Charges

curl -X POST \
  "https://api.partner.com/v1/charges" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "store123",
    "cart_id": "0e674fdf-f27e-4a39-9c3d-46ec59a361df",
    "user_token": "aW0gYSBsaXR0bGUgdGVhcIHNob3J0IGFuZCBzdG91dA",
    "total_amount": 5,
    "tax_amount": 1,
    "currency": "USD",
    "entrance_id": "qr11",
    "entry_timestamp": 1689172938805,
    "exit_timestamp": 1689172939050,
    "discounts": [
      {
        "amount": 5,
        "type": "percentage",
        "coupon_code": "5OFF",
        "description": "5% off"
      }
    ],
    "items": [
      {
        "sku": "DTSNLPCH",
        "name": "Diet Snapple",
        "quantity": 1,
        "unit_price": 5,
        "taxes": [
          {
            "sales_tax": 8.5,
            "type": "percentage"
          }
        ],
        "discounts": [
          {
            "amount": 2,
            "type": "absolute",
            "coupon_code": "2OFF",
            "description": "$2 off"
          }
        ]
      }
    ],
    "providers": [
      {
        "id": "partner_xyz",
        "data": {
          "auth_amount": 20,
          "card_last4": 1234
        }
      }
    ]
  }'

{
  "cart_id": "0e674fdf-f27e-4a39-9c3d-46ec59a361df",
  "transaction_id": "38e07e0e-c90d-47d5-866b-d506a21a4dcb",
  "status": "SUCCESS",
  "total_amount": 5,
  "tax_amount": 1,
  "paid_amounts": [
    {
      "payment_type": "stored-cash",
      "amount": 3.5
    },
    {
      "payment_type": "credit",
      "amount": 1.5
    }
  ]
}

Zippin calls the partner backend in the cloud to charge the final amount.

Request

URL

POST https://api.partner.com/v1/charges

Request Attributes

Attribute	Type	Description
store_id	string	The identifier of the store.
cart_id	string	The identifier of the Zippin cart.
user_token	string	The identifier of the shopper.
total_amount	number	Order amount to be charged.
tax_amount	number	Order tax amount, included in total_amount.
entrance_id	string	The identifier of the entrance from where the shopper entered the store.
entry_timestamp	number	Entry time of the shopper. Measured in milliseconds since the epoch.
exit_timestamp	number	Exit time of the shopper. Measured in milliseconds since the epoch.
currency	string	ISO 4217 currency code. For example, USD, NOK, and more.
items	string	An array of items (SKU, name, quantity, unit_price, taxes, discounts) in the cart. There must be at least one item in the cart.
providers	array	Array of JSON objects (id, data) containing the identifier of the partner and any other integration data sent to Zippin.

Response

Returns the charge details.

Response Attributes

Attribute	Type	Description
cart_id	string	(Optional) The identifier of the Zippin cart.
transaction_id	string	(Optional) The identifier of the transaction on the partner’s side. This can help Zippin map the cart to this transaction.
status	string	(Optional) Status of payment transaction - SUCCESS, FAILURE, or PARTIAL.
total_amount	number	Order amount that was charged.
tax_amount	number	Order tax amount, included in total_amount.
paid_amounts	array	An array of JSON objects specifying amounts charged per payment type. Amounts should add up to total_amount.

Refunds

curl -X POST \
  "https://api.partner.com/v1/refunds" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "store123",
    "cart_id": "0e674fdf-f27e-4a39-9c3d-46ec59a361df",
    "user_token": "aW0gYSBsaXR0bGUgdGVhcIHNob3J0IGFuZCBzdG91dA",
    "total_amount": 6.48,
    "currency": "USD",
    "refund_id": "6a474bde-f47c-6b34-ac2e-46ed59a452eb",
    "refund_timestamp": 1689172939089,
    "items": [
      {
        "sku": "DTSNLPCH",
        "name": "Diet Snapple",
        "quantity": 1,
        "unit_price": 5,
        "taxes": [
          {
            "sales_tax": 8.5,
            "type": "percentage"
          }
        ],
        "discounts": [
          {
            "amount": 2,
            "type": "absolute",
            "coupon_code": "2OFF",
            "description": "$2 off"
          }
        ]
      }
    ],
    "providers": [
      {
        "id": "payment_partner_xyz",
        "data": {
          "loyalty_id": "DFoLhapMRK2RRafSogLHMQ",
          "auth_amount": 20,
          "card_last4": 1234
        }
      }
    ]
  }'

{
  "refund_id": "6a474bde-f47c-6b34-ac2e-46ed59a452eb",
  "transaction_id": "49e07e0e-c60d-47r5-867b-d506a21a65rg"
}

Zippin calls the partner backend in the cloud to issue the refund.

If there is a dispute raised by a shopper, you can call the Dispute Cart API or contact Zippin Support.

Zippin receives the refund request.
A ticket is created for investigation.
If the refund is approved, Zippin calls the partner backend in the cloud to issue the refund.

Request

URL

POST https://api.partner.com/v1/refunds

Request Attributes

Attribute	Type	Description
store_id	string	The identifier of the store.
cart_id	string	The identifier of the Zippin cart.
user_token	string	The identifier of the shopper.
total_amount	number	The amount to be refunded.
currency	string	Transaction currency code in ISO 4217 3 Character Alphabetic Code.
refund_id	string	The identifier of the Zippin refund request. It's in the UUID v4 format and unique across refund requests.
refund_timestamp	number	Time when the refund was initiated. Measured in milliseconds since the epoch.
items	array	An array of items (SKU, name, quantity, unit_price, taxes and discounts) to be refunded in the cart.
providers	array	Array of JSON objects (id, and data) containing the identifier of the partner and any other integration data sent to Zippin as part of other API responses.

Response

Returns the refund details.

Response Attributes

Attribute	Type	Description
refund_id	string	(Optional) The identifier of the Zippin refund request. It's in the UUID v4 format and unique across refund requests.
transaction_id	string	(Optional) The identifier of the refund transaction on the partner’s side. This can help Zippin map the refund to this transaction.

Integration Guide

You will implement these APIs and provide endpoints to Zippin.

Loyalty Integration Guide

This document guides you (referred as Loyalty Partner) to integrate your loyalty system with Zippin checkout-free platform.

Loyalty partner is responsible for:

Verifying the scanned code and providing a long-lived loyalty ID to Zippin.
Providing the available discounts/promotions on items taken (purchased), based on the loyalty ID above.

Zippin is responsible for:

Collecting the code scanned by the shopper and sending it to loyalty partner to get long-lived loyalty ID. This loyalty ID is attached to the shopper’s cart.
Building a virtual cart comprising of items taken by the shopper.
Sending the virtual cart to loyalty partner with the loyalty ID to get promotions.
Applying the received promotions to the virtual cart.
If the loyalty partner supports the stored cash, Zippin sends the final amount to charge from the stored cash account otherwise Zippin charges the final amount.
If the loyalty partner supports the stored cash, Zippin sends the amount to be refunded from the stored cash account in the event of a dispute.

Core Integration Flow

Shopper enters the store for shopping.
Shops picks items to purchase.
Shopper scans loyalty bar or QR code on a loyalty scanner installed inside the store. Shopper can do this anytime before exiting the store.
Zippin calls the Loyalty ID API (implemented by the loyalty partner) to retrieve the Loyalty ID and attaches it to the shopper’s cart.
Shopper exits the store.
Zippin finalizes the cart, applies prices and taxes.
Zippin calls the Promotions API (implemented by the loyalty partner) to get the discounts/promotions applicable on the cart.
Zippin applies the received promotions.
If the loyalty partner supports the stored cash, Zippin sends the final amount to charge from the stored cash account otherwise Zippin charges the final amount.
If the loyalty partner supports the stored cash, Zippin sends the amount to be refunded from the stored cash account in the event of a dispute.

API Reference

Loyalty ID

If the scanned loyalty code is not long-lived, loyalty partner needs to implement the Loyalty ID API endpoint. Zippin calls this API to retrieve the long-lived Loyalty ID.

Promotions

If the loyalty partner supports promotion, implement the Promotions API to apply promotions to a cart.

Charges

If the loyalty partner supports stored cash to charge the shopper, implement the Charges API to charge the final amount.

Refunds

If the loyalty partner supports stored cash to charge the shopper, implement the Refunds API to issue the refund.

Payments Integration Guide

This document guides you (referred as Payments Partner) to integrate your payments system with Zippin checkout-free platform.

Payments Partner is responsible for billing by:

Authorizing the shopper to enter the store. This includes collecting the payment method, authorizing an amount, and other optional checks to ensure that the card is not in the deny list.
Charging the total order amount after the shopper exits from the store.

Zippin is responsible for checkout-free technology by:

Opening the turnstile gate and allowing authorized shoppers to enter the store.
Building a virtual cart comprising of items taken (purchased) by the shopper.

For billing the carts, there are two options:

Option 1: Zippin applies prices, taxes, and discounts to compute the final amount; and then sends the final amount to the Payments Partner for billing. Zippin generates the receipt for the shopper. See Core Integration Flow.
Option 2: Zippin sends the virtual cart to the Payments Partner. Payments Partner applies prices, taxes, and discounts to compute the final amount and charges the shopper. Payments Partner generates the receipt for the shopper.

Core Integration Flow

Payments Partner collects payment method and performs necessary checks to authorize the shopper to enter the store for shopping.
Payments Partner calls the Zippin Events API to submit person-access event within the store network with a user-token.
Zippin opens the gate for the shopper to enter the store.
Shopper shops and exits the store.
Zippin finalizes the cart, applies prices, taxes, and discounts to compute the final amount.
Zippin calls the Charges API (implemented by the Payments Partner) to charge the final amount.
In case of refunds, Zippin calls the Refunds API (implemented by the Payments Partner) to issue the refund.

API Reference

Events

Payment Partner calls the Zippin Events API to allow or deny store entry to the shopper.

Charges

Zippin calls the Payments Partner backend in the cloud to charge the final amount. Payments Partner needs to implement the Charges API.

Following are some sample scenarios that rarely occur. There is a solution to handle such scenarios.

Sample Scenario 1:In rare cases, a shopper may exit with items that are not captured in the original cart while the shopper was in the store. Shoppers are not charged for these items, which may result in loss of revenue. To address this, Zippin creates additional (correction) cart for the same user-token and sends it to the Payments Partner for billing. This is to ensure that all the items are accounted for.

Solution: For this, you must enable your system to process multiple carts for a user-token.

Sample Scenario 2: Zippin submits a cart and expects a 200 OK response. For some reason, if the response is delayed, may be due to network drop, it is possible that the cart gets submitted again for billing before Zippin receives success response. This is because Zippin optimizes for 100% billing ensuring each cart is billed accurately. In such scenarios, the cart may be submitted more than one time.

Solution: You must enable your system to accept the same cart multiple times. For example, if a shopper is already charged, and the same cart is submitted again, the cart must be ignored and a http 200 OK response must be returned.

Sample Scenario 3: If full refund for failed payment cart is processed, If shopper returned all the items for the failed payment Zippin submits a cart and expects a 200 OK response. For some reason, if the response is delayed, may be due to network drop, it is possible that the cart gets submitted again for billing before Zippin receives success response. This is because Zippin optimizes for 100% billing ensuring each cart is billed accurately. In such scenarios, the cart may be submitted more than one time.

Payment failure case

If the entire payment fails, send a response below with the FAILURE status.

{

"cart_id": "0e674fdf-f27e-4a39-9c3d-46ec59a361df",

"transaction_id": "38e07e0e-c90d-47d5-866b-d506a21a4dcb",

"status": "FAILURE",

"total_amount": 0,

"tax_amount": 0,

"paid_amounts": []

}

Partial payment case

If only partial payment is made, send reply below with PARTIAL status. Total amount purchased is $5 but only $2.5 is charged Send $2.5 in total_amount.

{

"cart_id": "0e674fdf-f27e-4a39-9c3d-46ec59a361df",

"transaction_id": "38e07e0e-c90d-47d5-866b-d506a21a4dcb",

"status": "PARTIAL",

"total_amount": 2.5,

"tax_amount": 0.5,

"paid_amounts": [{

"payment_type": "credit",

"amount": 2.5

}]

}

Refunds

Zippin calls the Payments Partner backend in the cloud to issue the refund. Payments Partner needs to implement the Refunds API.

Additional Integration Items

Configuration

Optional. Payment Partner calls the Zippin Configuration API to pull the latest configuration parameters.

Metrics

Optional. Payment Partner calls the Zippin Metrics API to send useful information like health, function, and performance of a store's subsystems.

Mobile App Integration Guide

This guide describes the procedure for integrating mobile app for Zippin’s check-out free platform. The mobile app integration enables a shopper to enter the store by scanning a QR code from their mobile phones versus a physical card.

In this document, Integration Partner refers to the entity that builds or maintains the mobile app, which in many cases is the retailer.

The mobile app generates a QR code for the shopper. The shopper scans the code at the store entry. Zippin Access Control validates the code:

If validated, the turnstile opens.
If not validated, turnstile remains locked.

The QR code can be validated in one of the following ways:

Zippin controlled QR Code or card reader

Zippin generated QR code (works offline) - Zippin has the DSA key pair (private key and public key both). Zippin generates QR code, shopper scans the QR code, and Zippin validates the scan.
Zippin QR code format (works offline) - Integration Partner generated QR code in the format specified by Zippin.
- Zippin generates DSA key pair, keeps the public key, and emails the private key to the Integration Partner.
- Integration Partner generates the QR Code using the private key.
- When a shopper scans the QR code in the store, Zippin validates the scan using the public key.
Custom QR code format - Integration Partner generated and Integration Partner format QR code.
- In this case, Zippin cannot validate the QR code and is required to call the Integration Partner’s API for QR code validation.

Partner controlled QR code or card reader

Integration Partner generates and validates the QR Code and calls Zippin Events API to submit person-access event within the store network with a user-token.

When shopper leaves, Zippin passes the cart information to the Integration Partner.

Integration Partner calculates tax, discounts, and amount due.
Integration Partner manages billing, receipts, and refunds.

Zippin Generated QR Code

API Specifications and Flow for Zippin Generated QR Code

After checking valid payment method on file, the Integration Partner must call the Zippin Get QR Code for the Shopper API, where the user-token is passed as a parameter. Zippin generates a QR code that is displayed on the shopper’s mobile app.
The shopper scans the QR code to enter the store.
Zippin validates the code and opens the gate allowing the shopper to enter the store.
Shopper shops and exits the store.

Partner Generated QR Code in Zippin Format

API Specifications and Flow for Integration Partner Generated QR Code in Zippin Format

This section describes the flow for validating the QR code generated by the Integration Partner in Zippin format.

Integration Partner generates the QR code using the private key and displays it on the shopper’s mobile app.
The shopper scans the QR code to enter the store.
Zippin captures the QR code and validates the scan using a public key.
On successful validation, Zippin opens the gate allowing the shopper to enter the store.
Shopper shops and exits the store.

Zippin QR Code Format

Sample Code using NodeJS

Generate the signature.

const privateKey = fs.readFileSync('privateKey.pem', 'utf-8');
message = 'v1:zipp:5579452f-8c6e-4997-827c-ac120d2174b3:1567628198079';
const signer = crypto.createSign('SHA256');
signer.update(message);
signer.end();
const signature = signer.sign(privateKey, 'base64');
console.log(signature)

Verify the Signature.

message = 'v1:zipp:5579452f-8c6e-4997-827c-ac120d2174b3:1567628198079';
signature = '<signature-to-be-verified>';
const publicKey = fs.readFileSync('publicKey.pem', 'utf-8');
const verifier = crypto.createVerify('SHA256');
verifier.update(message);verifier.end();
console.log(verifier.verify(publicKey, Buffer.from(signature, 'base64')));

Install cryptography package.

pip install cryptography

Generate the signature.

from base64 import b64encode, b64decode
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.serialization import load_pem_private_key
with open("privateKey.pem", "rb") as key_file: 
  private_key = load_pem_private_key(key_file.read(), None, default_backend())
message = b"v1:zipp:5579452f-8c6e-4997-827c-ac120d2174b3:1567628198079"
signature = private_key.sign(message, hashes.SHA256())
signature = b64encode(signature).decode('utf-8')
print(signature)

Verify the Signature.

from base64 import b64encode, b64decode
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.serialization import load_pem_public_key
with open("publicKey.pem", "rb") as key_file:
  public_key = load_pem_public_key(key_file.read(),default_backend())
message = b"v1:zipp:5579452f-8c6e-4997-827c-ac120d2174b3:1567628198079"
signature = "<signature-to-be-verified>"
signature = b64decode(signature.encode('utf-8'))
public_key.verify(signature, message, hashes.SHA256()) #throws cryptography.exceptions.InvalidSignature if it fails
print("verified.")

{version}:{retailer-code}:{user-token}:{expiry-time}:{signature}

Example:
v1:zipp:5579452f-8c6e-4997-827c-ac120d2174b3:1567628198079:L5rM/q2Q4NqIKDmsKAd9Vsw5hPHB1YKJ95ea8odOroic/SGRSs1zeQ==

Parameter	Description
version	The current version is v1. This can change if there is a change to the QR code format.
retailer-code	The name of the app in Zippin systems that is a pre-agreed upon string between the app and Zippin. In the example above, the string “zipp” is the name of the app.
user-token	This is the unique token that is assigned to a shopper. It must be alpha-numeric English characters with a maximum length of 250 characters. When the cart is finalized and submitted, the user-token is sent as one of the parameters.
expiry-time	This is the expiry time for the QR code. The time is in milliseconds since epoch in UTC. During validation, Zippin checks if the QR code is valid or not.
signature	This is the DSA signature generated using the private key.

Partner’s Custom QR Code

API Specifications and Flow for Integration Partner’s Custom QR Code

In this scenario, the QR code is generated by the Integration Partner in their own format. In this case, Zippin is unable to verify the QR code when the shopper scans the QR code, instead the Zippin Access Service reads the QR code and calls the Integration Partner's Authorizations API for QR code validation.

Integration Partner generates the QR code and displays it on the shopper’s mobile app.
The shopper scans the QR code to enter the store.
The Zippin Access Service reads the QR code and calls the Integration Partner's Authorizations API.
Based on the response received from the Authorizations API, the shopper is allowed or denied entry in the store.
If the response is Allow, Zippin opens the gate for the shopper to enter the store. Deny is optional.
The shopper shops and exits the store.

Partner Controlled Reader

API Specifications and Flow for Integration Partner Controlled Reader

This section describes the flow for Integration Partner controlled QR code or card reader.

After checking valid payment method on file, the Integration Partner generates a QR code that is displayed on the shopper’s mobile app.
It can be any code - bar code, employee badge, and so on.
The shopper scans the QR code to enter the store. The Integration Partner calls the Zippin Events API to submit person-access event within the store network with a user-token.
Zippin opens the gate allowing the shopper to enter the store.
Shopper shops and exits the store.

Events

Payment Partner calls the Zippin Events API to allow or deny store entry to the shopper.

Cart Submission and Billing

After the shopper leaves the store, Zippin finalizes and submits the cart using the Cart Submission API to Integration Partner backend in the cloud. Note that the cart submission is not instant. It can take several minutes, few hours, or in rare circumstances more than a day based on various factors. For this, you must ensure that the user-token is not expired and is still valid. This API payload consists of the user-token and the list of items purchased by the shopper. The Integration Partner is responsible for charging the shopper with the final order amount and also providing shopper receipts.

There is a time lag between shopper validation and when final amount is charged (or a refund issued). This lag can vary from a few seconds to hours, or in a system incident case, up to 3-4 days.

Error Scenarios

Error messages must be sent to Zippin only in the following scenarios:

There is a mismatch in the user-token or the user-token is not recognized by the app.
There is a mismatch in the SKU or the SKU is not recognized by the app.
Payload is not as per specifications provided.

Example Scenario 1: Zippin may create additional carts for a user-token and send them to the Integration Partner for billing. This may result in revenue loss for the Integration Partner, as shoppers are not charged for items in these additional carts. For example, Cart corrections. In such exceptional scenarios, if some items are missed in the original cart, Zippin creates an additional cart and sends it to the Integration Partner for billing to ensure that all the items are accounted for.

Solution: The Integration Partner must enable their system to process multiple carts for a user-token.

Example Scenario 2: Zippin submits a cart and expects a 200 Success response. For some reason, if the response is delayed, may be due to network drop, and before Zippin receives success response, the cart is submitted again. This is because Zippin optimizes for 100% billing ensuring each cart is billed accurately. In such scenarios, the cart may be submitted more than one time.

Solution: The Integration Partner must enable their system to accept the same cart multiple times. For example, if a shopper is already charged, and the same cart is submitted again, the cart must be ignored and a http 200 Success response must be returned.

Entry and Exit Notifications

When enabled, Zippin calls your Notifications API to send the shopper entry and exit event notifications. This API is not called again in case of failure. Only one entry and exit notification is sent in case of group shopping.

Zippin APIs

Authentication

Errors

Pagination

Get QR Code for the shopper

Dispute

The Dispute Object

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 a shelf

User

Add Users

Update Users

Retrieve a User

List all Users

Delete a User

Open Store Entrance

Reports

The Cart Object

The Cart Item Object

The Cart Payment Object

The Cart Refund Object

Carts

Carts Summary

System

Events

Configuration

Metrics

Retailer/Partner APIs

Cart Submission

Notifications

QR Code Validation

Webhook/Push Transactions

Transaction delivery behaviors

Cart submission behavior

Payment behavior

Refund behavior

Retry behavior

Loyalty ID

Promotions

Charges

Refunds

Integration Guide

Loyalty Integration Guide

Loyalty ID

Promotions

Charges

Refunds

Payments Integration Guide

Core Integration Flow

Events

Charges

Refunds

Additional Integration Items

Configuration

Metrics

Mobile App Integration Guide

Zippin controlled QR Code or card reader

Partner controlled QR code or card reader

Zippin Generated QR Code

Partner Generated QR Code in Zippin Format

Zippin QR Code Format

Partner’s Custom QR Code

Partner Controlled Reader

Events

Cart Submission and Billing

Entry and Exit Notifications