Zippin APIs

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

storeId is refers to tenant store id.

Authentication

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

Keep your API keys secure!

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

Errors

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

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

Pagination

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

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

API Versioning and Support Policy

API changes are versioned and currently on v1. When backwards-incompatible changes are made, a new version is released. To prevent breaking your code, we do not update your version until you are ready to upgrade.

Backwards-compatible changes include the following:

Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses.
Changing the order of properties in existing API responses.

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,
  "taxes": [{"code": "sales_tax", "value": 8.75}],
  "categories": ["miscellaneous"],
  "upcCode": "K0001",
  "receiptName": "Kale and Quinoa Salad",
  "tags": ["salad", "veggies"]
}'

{
  "id": "KQS2X12",
  "name": "Kale and Quinoa Salad",
  "created": 1552088527,
  "updated": 1552088527,
  "deleted": false,
  "unitWeight": 253,
  "thumbnails": ["https://images.example.com/KQS2X12_1.jpg", "https://images.example.com/KQS2X12_2.jpg"],
  "storeIds": ["teststore1", "teststore2"],
  "price": 5,
  "taxes": [{"code": "sales_tax", "value": 8.75, "valueType": "percentage"}],
  "categories": ["miscellaneous"],
  "upcCode": "K0001",
  "receiptName": "Kale and Quinoa Salad",
  "tags": ["salad", "veggies"]
}

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	Optional. An array of category codes. Defaults to default category.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	An array of category codes.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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,
    "taxes": [{"code": "sales_tax", "value": 8.75}],
    "categories": ["miscellaneous"],
    "upcCode": "K0001",
    "receiptName": "Kale and Quinoa Salad",
    "tags": ["salad", "veggies"]
  }'

{
    "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,
    "taxes": [{"code": "sales_tax", "value": 8.75}],
    "categories": ["miscellaneous"],
    "upcCode": "K0001",
    "receiptName": "Kale and Quinoa Salad",
    "tags": ["salad", "veggies"]
}

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	Optional. An array of category codes. Defaults to default category.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	An array of category codes.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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,
    "taxes": [{"code": "sales_tax", "value": 8.75}],
    "categories": ["miscellaneous"],
    "upcCode": "K0001",
    "receiptName": "Kale and Quinoa Salad",
    "tags": ["salad", "veggies"]
}

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	An array of category codes.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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,
        "taxes": [{"code": "sales_tax", "value": 8.75}],
        "categories": ["miscellaneous"],
        "upcCode": "K0001",
        "receiptName": "Kale and Quinoa Salad",
        "tags": ["salad", "veggies"]
    },
    {...},
    {...}
  ]
}

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	An array of category codes.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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,
    "taxes": [{"code": "sales_tax", "value": 8.75}],
    "categories": ["miscellaneous"],
    "upcCode": "K0001",
    "receiptName": "Kale and Quinoa Salad",
    "tags": ["salad", "veggies"]
}

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. Price is mandatory only if the shopper is charged through the Zippin payment service.
taxes	array	Optional. An array of taxes applied to the SKU. Defaults to an empty array. Ex: `taxes: [{"code": "sales_tax", "value": 8.75}]` represents 8.75%. The percentage or fixed amount is determined based on the tax type defined in the master data. It supports upto 4 decimal places; if there are more than four decimal places, the value will be rounded to four decimal places. For example, 8.75968 will be rounded to 8.7597, and 8.75124 will be rounded to 8.7512.
categories	array	An array of category codes.
upcCode	string	Optional. The UPC code of the SKU.
receiptName	string	Optional. The receipt name of the SKU. This name will be displayed on the receipt. If left blank, the name of the SKU will be displayed on the receipt.
tags	array	Optional. An array of tags. Defaults to an empty array.

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.

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.

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.

Push Transactions

curl -X POST \
  "https://api.retailer.example.com/v1/transactions" \
  -H "Authorization: Bearer eyJpdiI6ImRLY29wdzA5dVVBWkw0SGQ5aUdXZ0E9PSIsInZhbUmRmNmDE" \
  -H "Content-Type: application/json" \
  -d '{
      "cartId": "o-sep14-reports-03",
      "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"
            }
          ]
        },
        {
          "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"
            }
          ]
        }
      ],
      "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-16T03: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-16T10:40:29.000Z",
          "paymentReferenceId": "89992592779951686497",
          "paymentMode": "Credit/debit card",
          "last4": "1003",
          "brand": "VISA"
        }
      ],
      "refunds": [
        {
          "refundAmount": 1.56,
          "refundDate": "2022-09-16T03:39:47.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 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.

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.

Response

Returns the success or failure HTTP status code.

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.

Zippin APIs

Authentication

Errors

Pagination

API Versioning and Support Policy

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

Reports

The Cart Object

The Cart Item Object

The Cart Payment Object

The Cart Refund Object

Carts

Carts Summary

Retailer/Partner APIs

Cart Submission

Notifications

QR Code Validation

Push Transactions

Loyalty ID

Promotions

Charges

Refunds

Integration Guide

Loyalty Integration Guide

Loyalty ID

Promotions

Charges

Refunds