Raw purchase API Resource

Raw purchases are exactly the same as regular purchases made through the eStore endpoints, except for the fact that they are not based on shopping carts from the eStore endpoints. Raw purchases can come from any kind of external source or system.

POST /estore/raw-purchase/_calculate-tax-rate

Calculates tax rate for the given products.

NOTE: For US only: If there is no nexus in the state of the receiver, the tax rate will be zero, and amountExcludingTax will be equal to amountIncludingTax on all prices.

NOTE: When calculating amounts from quantities there might be some natural inconsistency between amountExcludingTax and amountIncludingTax due to the way we calculate tax per quantity (as opposed to the whole sum) and round half up for each quantity. This is true for both internal and external calculations, but only the "calculated" amount could potentially be different. For external calculations, only amountIncludingTax could differ.

Example:
External (US)

Request
unitPriceExcludingTax: 176.25
discountExcludingTax: 13.37
quantity: 2
(VAT: 30%)

Response
unitPriceIncludingTax: 229.13
unitPriceExcludingTax: 176.25
discountIncludingTax: 17.38
discountExcludingTax: 13.37
amountIncludingTax: 260.88
amountExcludingTax: 339.13

As a result, all calculations add up independently, but when you actually try to derive excluding vat from the amountIncludingTax, it does not add up.

176.25 * 2 - 13.36 = 339.14
229.13 * 2 - 17.38 = 440.88
but
339.13 * 1.3 = 440.8692307692308 ~= 440.87 != 440.88

This is correct, though, since what the customer sees and pays for is the price calculated for each qty (176.25 and 229.13).

Request Parameters
name type description
X-Instance-Id header Identifies the merchant instance, required for all API calls.
X-Language header Specifies the requested language of a resource, for example sv. If not present, this will default to a pre-configured language, most commonly en.
Request Body
media type data type description
application/json TaxRateRequest The lines to calculate the tax rate for.
Response Codes
code condition
200 The tax rates were calculated successfully
400 Given input parameters are incorrect, a more descriptive error message is provided in the response body.
Response Body
media type data type description
application/json TaxRateResponse The tax rate for the given products.

Example

Request
POST /estore/raw-purchase/_calculate-tax-rate
Content-Type: application/json
Accept: application/json
X-Instance-Id: ...
X-Language: ...

                
{
  "countryCode" : "SE",
  "shippingFeeExcludingTax" : 9.99,
  "paymentFeeExcludingTax" : 0.99,
  "serviceFeeExcludingTax" : 1.99,
  "receiverAddress" : {
    "addressLine1" : "Druveforsvägen 8",
    "city" : "BORÅS",
    "zipcode" : "50454",
    "administrativeDivision" : "Borås kommun"
  },
  "orderLines" : [ {
    "lineId" : 1,
    "stockKeepingUnitId" : 379667,
    "priceLookUpNumber" : "57968634",
    "unitPriceExcludingTax" : 99.99,
    "quantity" : 3,
    "discountExcludingTax" : 10.0
  }, {
    "lineId" : 12345,
    "stockKeepingUnitId" : 12345,
    "priceLookUpNumber" : "...",
    "unitPriceExcludingTax" : 12345.0,
    "quantity" : 12345,
    "discountExcludingTax" : 12345.0
  } ]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "shippingFee" : {
    "amountIncludingTax" : 29.99,
    "amountExcludingTax" : 22.49,
    "taxRate" : 0.25,
    "fixedTaxRate" : true
  },
  "paymentFee" : {
    "amountIncludingTax" : 29.99,
    "amountExcludingTax" : 22.49,
    "taxRate" : 0.25,
    "fixedTaxRate" : true
  },
  "serviceFee" : {
    "amountIncludingTax" : 29.99,
    "amountExcludingTax" : 22.49,
    "taxRate" : 0.25,
    "fixedTaxRate" : true
  },
  "orderLines" : [ {
    "lineId" : 1,
    "stockKeepingUnitId" : 379667,
    "priceLookUpNumber" : "57968634",
    "unitPriceIncludingTax" : 12.76,
    "unitPriceExcludingTax" : 10.21,
    "discountIncludingTax" : 26.49,
    "discountExcludingTax" : 21.19,
    "amountIncludingTax" : 11.79,
    "amountExcludingTax" : 9.44,
    "taxRate" : 0.25
  }, {
    "lineId" : 12345,
    "stockKeepingUnitId" : 12345,
    "priceLookUpNumber" : "...",
    "unitPriceIncludingTax" : 12345.0,
    "unitPriceExcludingTax" : 12345.0,
    "discountIncludingTax" : 12345.0,
    "discountExcludingTax" : 12345.0,
    "amountIncludingTax" : 12345.0,
    "amountExcludingTax" : 12345.0,
    "taxRate" : 12345.0
  } ]
}

POST /estore/raw-purchase/purchases

Creates a new raw purchase with the given information.

Request Parameters
name type description
X-Instance-Id header Identifies the merchant instance, required for all API calls.
X-Language header Specifies the requested language of a resource, for example sv. If not present, this will default to a pre-configured language, most commonly en.
Request Body
media type data type description
application/json RawPurchaseRequest The purchase to create.
Response Codes
code condition
201 The purchase was created successfully
400 Given input parameters are incorrect, a more descriptive error message is provided in the response body.
Response Body
media type data type description
application/json RawPurchaseResponse The result of creating the purchase.

Example

Request
POST /estore/raw-purchase/purchases
Content-Type: application/json
Accept: application/json
X-Instance-Id: ...
X-Language: ...

                
{
  "socialSecurityNumber" : "...",
  "firstName" : "...",
  "lastName" : "...",
  "organizationNumber" : "...",
  "companyName" : "...",
  "email" : "...",
  "alternativeEmailAddress" : "...",
  "landline" : "...",
  "cellphone" : "...",
  "gender" : "MAN",
  "additionalOrderText" : "...",
  "sellerDepartment" : "...",
  "sellerPerson" : "...",
  "notes" : "...",
  "nextDeliveryDate" : "...",
  "orderDate" : "...",
  "languageCode" : "sk",
  "dateOfBirth" : "...",
  "customFields" : [ {
    "code" : "...",
    "value" : "..."
  }, {
    "code" : "...",
    "value" : "..."
  } ],
  "remoteAddress" : "...",
  "address" : {
    "countryCode" : "SE",
    "addressLine1" : "Druveforsvägen 8",
    "careOf" : "...",
    "city" : "BORÅS",
    "zipcode" : "50454",
    "administrativeDivision" : "..."
  },
  "deliveryAddress" : {
    "firstName" : "...",
    "lastName" : "...",
    "companyName" : "Viskan System AB",
    "countryCode" : "SE",
    "addressLine1" : "Druveforsvägen 8",
    "careOf" : "...",
    "city" : "BORÅS",
    "zipcode" : "50454",
    "administrativeDivision" : "..."
  },
  "integritiesMap" : {
    "EMAIL_INFO" : true,
    "SMS_INFO" : false
  },
  "customerNumber" : "...",
  "paymentMethodName" : "...",
  "deliveryMethodName" : "...",
  "deliveryPointCode" : "...",
  "termsOfDeliveryCode" : "...",
  "termsOfPaymentCode" : "...",
  "marketingCampaignCode" : "...",
  "storeNumber" : "...",
  "methodOfArrivalNumber" : "...",
  "discount" : 12345.0,
  "googleAnalyticsId" : "...",
  "rows" : [ {
    "stockKeepingUnitId" : 12345,
    "priceLookUpNumber" : "...",
    "discountIncludingTax" : 12345.0,
    "quantity" : 1,
    "discountExcludingTax" : 12345.0,
    "taxRate" : 0.25,
    "unitPriceExcludingTax" : 12345.0,
    "unitPriceIncludingTax" : 12345.0
  }, {
    "stockKeepingUnitId" : 12345,
    "priceLookUpNumber" : "...",
    "discountIncludingTax" : 12345.0,
    "quantity" : 12345,
    "discountExcludingTax" : 12345.0,
    "taxRate" : 12345.0,
    "unitPriceExcludingTax" : 12345.0,
    "unitPriceIncludingTax" : 12345.0
  } ],
  "subscriptions" : [ {
    "templateCode" : "...",
    "createInitialOrderDirectly" : true
  }, {
    "templateCode" : "...",
    "createInitialOrderDirectly" : true
  } ],
  "flexibleSubscriptions" : [ {
    "interval" : 12345,
    "createInitialOrderDirectly" : true,
    "rows" : [ {
      "stockKeepingUnitId" : 12345,
      "discounts" : [ { }, { } ],
      "priceLookUpNumber" : "...",
      "quantity" : 1,
      "taxRate" : 0.25,
      "unitPriceExcludingTax" : 12345.0,
      "unitPriceIncludingTax" : 12345.0
    }, {
      "stockKeepingUnitId" : 12345,
      "discounts" : [ { }, { } ],
      "priceLookUpNumber" : "...",
      "quantity" : 12345,
      "taxRate" : 12345.0,
      "unitPriceExcludingTax" : 12345.0,
      "unitPriceIncludingTax" : 12345.0
    } ]
  }, {
    "interval" : 12345,
    "createInitialOrderDirectly" : true,
    "rows" : [ {
      "stockKeepingUnitId" : 12345,
      "discounts" : [ { }, { } ],
      "priceLookUpNumber" : "...",
      "quantity" : 12345,
      "taxRate" : 12345.0,
      "unitPriceExcludingTax" : 12345.0,
      "unitPriceIncludingTax" : 12345.0
    }, {
      "stockKeepingUnitId" : 12345,
      "discounts" : [ { }, { } ],
      "priceLookUpNumber" : "...",
      "quantity" : 12345,
      "taxRate" : 12345.0,
      "unitPriceExcludingTax" : 12345.0,
      "unitPriceIncludingTax" : 12345.0
    } ]
  } ],
  "paymentReferences" : [ {
    "amount" : 12345.0,
    "reference" : "...",
    "externalReference" : "...",
    "paymentMethodCode" : "...",
    "paymentMethodType" : "...",
    "transactionType" : "SALE",
    "forSubscription" : true,
    "forOrder" : true,
    "parentReference" : "..."
  }, {
    "amount" : 12345.0,
    "reference" : "...",
    "externalReference" : "...",
    "paymentMethodCode" : "...",
    "paymentMethodType" : "...",
    "transactionType" : "AUTHORIZATION",
    "forSubscription" : true,
    "forOrder" : true,
    "parentReference" : "..."
  } ],
  "serviceFeeTaxRate" : 12345.0,
  "serviceFeeIncludingTax" : 12345.0,
  "serviceFeeExcludingTax" : 12345.0,
  "shippingFeeTaxRate" : 12345.0,
  "shippingFeeIncludingTax" : 12345.0,
  "shippingFeeExcludingTax" : 12345.0,
  "paymentFeeTaxRate" : 12345.0,
  "paymentFeeIncludingTax" : 12345.0,
  "paymentFeeExcludingTax" : 12345.0
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "purchaseNumber" : "..."
}