Skip to content

purchase.adoc

Latest commit

 

History

History
549 lines (497 loc) · 17.8 KB

purchase.adoc

File metadata and controls

549 lines (497 loc) · 17.8 KB

Purchase API V1

Service Description

The purchase API provides information about purchases made through the iZettle point-of-sale.

Scopes

The Purchase API implements the following scopes:

  • READ:PURCHASE

Version 2

There is a version 2 of this API. The only difference is in how payments are represented. In order to be sure to get all purchases, including those paid with invoices, you need to use version 2. Follow the link below for more detailed documentation.

OBSERVE!

Due to backwards compatability requirements with some of our clients, some endpoints in the version 1 API will not return purchases that lack cardPayments or cashPayments. This means that any purchase that was paid by invoice – or by some payment type other than card or cash – may be missing in the results. To be sure to receive all purchases you must use the version 2 API.

Get purchase history

Will include cash register information if possible.

GET /purchases

lastPurchaseHash (optional)

A value from "lastPurchaseHash" from the result of a previous history query, to continue listing purchases from the next record after the previous query.

startDate (optional)

The start date (inclusive) for purchases to be retrieved from until today or endDate. Can only be combined with endDate or limit.

endDate (optional)

The last date (exclusive) for purchases to be retrieved until. Can only be combined with startDate.

limit (optional)

The maximum number of records to return.

descending (optional)

When true, returns purchases with the highest timestamp first. When false, returns purchases with the lowest timestamp first. Defaults to false if not specified.

Fields named "*UUID1" are the standard UUID Type 1 (8-4-4-4-12) representation of the UUID fields. The UUID fields can be either of:

  1. Base64 encoded UUID.

  2. A Long purchase ID. This is the case for purchases several years old and in these cases there can be no UUID representation so the *UUID1 fields will be null

Permissions required

READ:PURCHASE

Example response 1

GET /purchases?limit=10

{
  "purchases": [
    {
      "purchaseUUID": "6HbDrnUNRji5iniGikNLiQ",
      "purchaseUUID1" : "fe8d0460-21c4-11e6-8ca8-3a4023ced819",
      "amount": 1500,
      "vatAmount": 161,
      "country": "SE",
      "currency": "SEK",
      "timestamp": "2015-02-08T10:21:21.469+0000",
      "gpsCoordinates": {
        "longitude": 18.44447366482676,
        "latitude": 60.416075632611964,
        "accuracyMeters": 65
      },
      "purchaseNumber": 1,
      "userDisplayName": "Ford Prefect",
      "userId": 1713921,
      "organizationId": 14184411,
      "products": [
        {
          "quantity": "1",
          "revisionId": 86695765,
          "vatPercentage": 12,
          "unitPrice": 1500,
          "rowTaxableAmount": 1339,
          "name": "Enkel espresso",
          "productId": 32704190,
          "comment": "Med soya mjölk",
          "autoGenerated": false,
          "libraryProduct": true
        }
      ],
      "cardPayments": [
        {
          "cardPaymentUUID": "aDvfSXWDRb-NmbbwMegqdA",
          "cardPaymentUUID1": "683bdf49-7583-45bf-8d99-b6f031e82a74",
          "amount": 1500,
          "cardType": "MASTERCARD",
          "maskedPan": "518779******5289",
          "cardPaymentEntryMode": "EMV",
          "applicationIdentifier": "A0000000041010",
          "terminalVerificationResults": "0000008000",
          "transactionStatusInformation": "E800",
          "referenceNumber": "N4GVFINIER",
          "nrOfInstallments": 0
        }
      ],
      "cashRegister": {
        "uuid": "r_dBcr6tT2ypC1jlMuUUzg",
        "displayName": "Kassa 1"
      },
      "receiptCopyAllowed": true,
      "groupedVatAmounts": {
        "12.0": 1500
      },
      "refund": false,
      "refunded": false
    },
    {
      "purchaseUUID": "zj9yI1wyTvqP46AG8NEaYg",
      "purchaseUUID1" : "ce3f7223-5c32-4efa-8fe3-a006f0d11a62",
      "amount": 1500,
      "vatAmount": 161,
      "country": "SE",
      "currency": "SEK",
      "timestamp": "2015-02-08T10:22:08.355+0000",
      "gpsCoordinates": {
        "longitude": 17.53335989364865,
        "latitude": 58.772674182845805,
        "accuracyMeters": 65
      },
      "purchaseNumber": 2,
      "userDisplayName": "Ford Prefect",
      "userId": 1713921,
      "organizationId": 14184411,
      "products": [
        {
          "quantity": "1",
          "revisionId": 86695765,
          "vatPercentage": 12,
          "unitPrice": 1500,
          "rowTaxableAmount": 1339,
          "name": "Enkel espresso",
          "productId": 32704190,
          "autoGenerated": false,
          "libraryProduct": true
        }
      ],
      "cashPayments": [
        {
          "cashPaymentUUID": "54f3gL8aToKG10bXOfj-IQ",
          "amount": 1500,
          "handedAmount": 10000
        }
      ],
      "cashRegister": {
        "uuid": "r_dBcr6tT2ypC1jlMuUUzg",
        "displayName": "Kassa 1"
      },
      "receiptCopyAllowed": true,
      "groupedVatAmounts": {
        "12.0": 1500
      },
      "refund": false,
      "refunded": false
    }
  ],
  "firstPurchaseHash": "14233908814696HbDrnUNRji5iniGikNLiQ",
  "lastPurchaseHash": "1423390928355zj9yI1wyTvqP46AG8NEaYg"
}

Example response 2 (partial refund)

{
  "purchases": [
    {
      "purchaseUUID": "DpNWkI7EEeaR8yfR3nmUIA",
      "amount": 17000,
      "country": "SE",
      "currency": "SEK",
      "timestamp": "2016-10-10T08:32:23.487+0000",
      "gpsCoordinates": {
        "longitude": 18.06672200650736,
        "latitude": 59.3343190127951,
        "accuracyMeters": 65
      },
      "purchaseNumber": 9,
      "userDisplayName": "Ford Prefect",
      "userId": 1713921,
      "organizationId": 14184411,
      "products": [
        {
          "quantity": "1",
          "revisionId": 108880736,
          "unitPrice": 7500,
          "rowTaxableAmount": 7500,
          "name": "Vetelevain",
          "variantName": "Hel",
          "imageLookupKey": "rg_yCe-BAR02O-7z_Jojj10v3OE.png",
          "productId": 36653619,
          "autoGenerated": false,
          "libraryProduct": true
        },
        {
          "quantity": "1",
          "revisionId": 108881416,
          "unitPrice": 6000,
          "name": "Källarfranska",
          "variantName": "Tio styck",
          "imageLookupKey": "jT6TDD_SopPLl8kzwauiRTbdlz0.png",
          "productId": 36653667,
          "autoGenerated": false,
          "libraryProduct": true
        },
        {
          "quantity": "1",
          "revisionId": 108881410,
          "unitPrice": 3500,
          "rowTaxableAmount": 3500,
          "name": "Baguette",
          "variantName": "Styckvis",
          "imageLookupKey": "on-pr7FqXvoBfa4WoE9zbNqkoWU.png",
          "productId": 36653662,
          "autoGenerated": false,
          "libraryProduct": true
        }
      ],
      "cashPayments": [
        {
          "cashPaymentUUID": "1137e9b0-8ec4-11e6-9f8b-eb0ea36a94e2",
          "amount": 17000,
          "handedAmount": 17000,
          "cashPaymentUUID1": "1137e9b0-8ec4-11e6-9f8b-eb0ea36a94e2"
        }
      ],
      "refundedByPurchaseUUIDs": [
        "HKXEKo7EEeaq_0GG8pcFtg"
      ],
      "receiptCopyAllowed": true,
      "published": true,
      "purchaseUUID1": "0e935690-8ec4-11e6-91f3-27d1de799420",
      "refundedByPurchaseUUIDs1": [
        "1ca5c42a-8ec4-11e6-aaff-4186f29705b6"
      ],
      "groupedVatAmounts": {},
      "refund": false,
      "refunded": true
    },
    {
      "purchaseUUID": "HKXEKo7EEeaq_0GG8pcFtg",
      "amount": -3500,
      "country": "SE",
      "currency": "SEK",
      "timestamp": "2016-10-10T08:32:42.675+0000",
      "gpsCoordinates": {
        "longitude": 18.06689298534442,
        "latitude": 59.33430848180441,
        "accuracyMeters": 65
      },
      "purchaseNumber": 10,
      "userDisplayName": "Ford Prefect",
      "userId": 1713921,
      "organizationId": 14184411,
      "products": [
        {
          "quantity": "-1",
          "unitPrice": 3500,
          "rowTaxableAmount": -3500,
          "name": "Baguette",
          "variantName": "Styckvis",
          "productId": 36653662,
          "autoGenerated": false,
          "libraryProduct": true
        }
      ],
      "cashPayments": [
        {
          "cashPaymentUUID": "1ca7c4f0-8ec4-11e6-93fb-440a20c6bcbf",
          "amount": -3500,
          "handedAmount": -3500,
          "cashPaymentUUID1": "1ca7c4f0-8ec4-11e6-93fb-440a20c6bcbf"
        }
      ],
      "refundsPurchaseUUID": "DpNWkI7EEeaR8yfR3nmUIA",
      "receiptCopyAllowed": true,
      "published": true,
      "purchaseUUID1": "1ca5c42a-8ec4-11e6-aaff-4186f29705b6",
      "refundsPurchaseUUID1": "0e935690-8ec4-11e6-91f3-27d1de799420",
      "groupedVatAmounts": {},
      "refund": true,
      "refunded": false
    }
  ],
  "firstPurchaseHash": "14297979780492DpNWkI7EEeaR8yfR3nmUIA",
  "lastPurchaseHash": "1476088362675HKXEKo7EEeaq_0GG8pcFtg"
}

Example response 3 (discounts)

{
  "purchases": [
    {
      "purchaseUUID": "biqV4OiTEea6-larSAFA7w",
      "amount": 10000,
      "vatAmount": 1331,
      "country": "SE",
      "currency": "SEK",
      "timestamp": "2017-02-01T15:31:00.648+0000",
      "purchaseNumber": 1507,
      "userDisplayName": "Ford Prefect",
      "userId": 1713921,
      "organizationId": 14184411,
      "products": [
        {
          "quantity": "2",
          "productUuid": "39cde734-e893-11e6-b8f1-2d3db21fba6a",
          "variantUuid": "302b4d5c-e893-11e6-b8f1-2d3db21fba6a",
          "vatPercentage": 25,
          "unitPrice": 2000,
          "rowTaxableAmount": 2240,
          "name": "Foo",
          "variantName": "",
          "discount": {
            "quantity": 1,
            "amount": 500
          },
          "discountValue": 500,
          "autoGenerated": false,
          "libraryProduct": true
        },
        {
          "quantity": "10",
          "productUuid": "4385c5ee-e893-11e6-b8f1-2d3db21fba6a",
          "variantUuid": "3bdf6232-e893-11e6-b8f1-2d3db21fba6a",
          "vatPercentage": 12,
          "unitPrice": 1000,
          "rowTaxableAmount": 6429,
          "name": "Bar",
          "variantName": "",
          "discount": {
            "quantity": 1,
            "percentage": 10
          },
          "discountValue": 1000,
          "autoGenerated": false,
          "libraryProduct": true
        }
      ],
      "discounts": [
        {
          "name": "",
          "percentage": 20,
          "quantity": 1
        }
      ],
      "cashPayments": [
    {
      "cashPaymentUUID": "6f4e2e50-e893-11e6-a784-a603fda22c92",
      "amount": 10000,
      "handedAmount": 10000,
      "cashPaymentUUID1": "6f4e2e50-e893-11e6-a784-a603fda22c92"
    }
  ],
  "receiptCopyAllowed": true,
  "published": true,
  "purchaseUUID1": "6e2a95e0-e893-11e6-bafa-56ab480140ef",
  "groupedVatAmounts": {
    "12.0": 7200,
    "25.0": 2800
  },
  "refund": false,
  "refunded": false
}
  ],
  "firstPurchaseHash": "1485857753809PaSsMOeeEeawkeLVV_68nw",
  "lastPurchaseHash": "1485858080407AOjsYOefEeax5pDdmnaGXw"
}

Get purchase details

GET /purchase/{purchaseUUID}

Permissions required

READ:PURCHASE

purchaseUUID

The UUID of the purchase

Errors

404

Purchase not found

Example response

GET /purchase/6HbDrnUNRji5iniGikNLiQ

{
    "purchaseUUID": "6HbDrnUNRji5iniGikNLiQ",
    "purchaseUUID1" : "e876c3ae-750d-4638-b98a-78868a434b89",
    "amount": 1500,
    "vatAmount": 161,
    "country": "SE",
    "currency": "SEK",
    "timestamp": "2015-02-08T10:21:21.469+0000",
    "gpsCoordinates": {
        "longitude": -73.99845698202617,
        "latitude": 40.734215418008596,
        "accuracyMeters": 65
    },
    "purchaseNumber": 1,
    "userDisplayName": "Stig Haraldsson",
    "products": [
        {
            "quantity": "1",
            "revisionId": 86695765,
            "vatPercentage": 12,
            "unitPrice": 1500,
            "rowTaxableAmount": 1339,
            "name": "Enkel espresso",
            "productId": 32704190,
            "autoGenerated": false,
            "libraryProduct": true
        }
    ],
    "cardPayments": [
        {
            "cardPaymentUUID": "aDvfSXWDRb-NmbbwMegqdA",
            "cardPaymentUUID1": "683bdf49-7583-45bf-8d99-b6f031e82a74",
            "amount": 1500,
            "cardType": "MASTERCARD",
            "maskedPan": "540200******7008",
            "cardPaymentEntryMode": "EMV",
            "applicationIdentifier": "A0000000041010",
            "terminalVerificationResults": "0000008000",
            "transactionStatusInformation": "E800",
            "referenceNumber": "N4GVFINIER",
            "nrOfInstallments": 0
        }
    ],
    "cashRegister": {
        "uuid": "r_dBcr6tT2ypC1jlMuUUzg",
        "displayName": "Kassa 1"
    },
    "receiptCopyAllowed": true,
    "refund": false,
    "groupedVatAmounts": {
        "12.0": 1500
    },
    "refunded": false
}

Discounts

Discounts can exist both on a specific row of items in the shopping cart, as well as on the entire shopping cart. Discounts on a row of items is applied on the whole amount of the row. A discount can be set either as a percentage or as a fixed value.

When applying the total discounts on the purchase price, the row discounts will first be applied, followed by the cart discount which is then applied on the sum of the already discounted row prices.

VAT calculation when discounts have been applied

VAT is calculated after all the discounts have been applied. Since each row can have a separate VAT percentage the cart discount is evenly distributed over all row of items before the VAT per row of products can be calculated.

If the cart discount is a fixed value then that value will be deducted from each row according the price of each row in relation to the total purchase price.

Examples

If the cart discount is 20%, then the price of each row of item will be deducted with 20% before calculating the VAT for each row.

If a purchase has a total price of 100 and contains two rows with the first row priced at 40 and the second at 60, then 40% of the fixed cart discount will be deducted from the first row and 60% from the other row before calculating the VAT.

Response structure

Row discounts are expressed using the following JSON structure in the products list, containing either amount for fixed discounts or percentage for percentage discounts. The discountValue field following the discount structure contains the total discount amount for the row:

"discount": {
  "quantity": 1,
  "percentage": 10
},
"discountValue": 1000

Note: Currently, we only support one discount per row of items, so the quantity field will always be set to 1. This could potentially change in the future.

Cart discounts are expressed using the following JSON structure in the root structure of the purchase. They can also contain either an amount or a percentage value:

"discounts": [
{
    "name": "",
    "amount": 2000,
    "quantity": 1
}

Note: Currently, we only support one discount per cart, so the discounts list will only contain one item with quantity set to 1. This could potentially change in the future.

See further below for a full response example containing discounts.

Example

Lets observe an example purchase, containing both discounts on rows as well as on the cart itself:

Product Unit price Amount Discount

Foo

20

2

5

Bar

10

10

10%

Cart discount

 20%

To calculate the total discount, we start by calculating the discount per row. The first row contains 2 item and has a fixed discount amount of 5.

The second row contains 10 items and a percentage discount of 10%:

Row discounts = 5 + 10 x 10 x 0.1 = 15.

Then we calculate the cart discount, based on the sum of the previously discounted rows:

Sum of discounted rows = 20 x 2 + 10 x 10 - 15 = 125.

Cart discount = 125 x 0.2 = 25

So the total discount on this purchase is: 15 + 25 = 40. And the total sum to pay is: 140 - 40 = 100.

A discount can never be greater than the actual amount of the row or cart price.

How to load all purchases for a user

You should never retrieve all the purchases in one request, since that can potentially put too much load on the server causing the request to be rejected or time out.

Instead, you should request the purchases splitted up into "pages", using the limit and lastPurchaseHash parameters.

The limit parameter will set the page size, and the lastPurchaseHash parameter sets the starting point from where to retrieve purchases. Every response from the purchase service will contain a lastPurchaseHash field, which can be added to the new request to retrieve the next "page".

In order to load all purchases, begin with an initial request without the lastPurchaseHash parameter being set, this will retrieve the first n purchases (where n is the page size defined by the limit parameter):

GET /purchases?limit=100

The result will contain the first n number of purchases.

{
  "purchases": [
    ....
  ],
  "firstPurchaseHash": "14233908814696HbDrnUNRji5iniGikNLiQ",
  "lastPurchaseHash": "1423390928355zj9yI1wyTvqP46AG8NEaYg"
}

To retrieve the following pages, use the lastPurchaseHash field in the previous response to load the next page:

GET /purchases?limit=100&lastPurchaseHash=1423390928355zj9yI1wyTvqP46AG8NEaYg

The result will contain the next n number of purchases:

{
  "purchases": [
    ....
  ],
  "firstPurchaseHash": "1423390928355zj9yI1wyTvqP46AG8NEaYg",
  "lastPurchaseHash": "1426265546490RPXdoMmDEeSg5Gw_2s_ZrQ"
}

Continue this process by using the lastPurchaseHash in the previous response as a request parameter in the following request until you receive an empty result.

If you want to be able to load new purchases later on, then store the last used lastPurchaseHash and use that to continue retrieving new purchases at a later time.