This integration method might be used when it is difficult or impossible to inject VAT calculation mechanism into the checkout process.
In other case it is better to use this method API description for manual connection to EAS system (online VAT calculation)
These methods might be used when VAT calculated on the store side and orders will be processed by the EAS solution as is or if store platform does not support VAT calculation, then VAT will be calculated for the orders treating prices as VAT inclusive.
Start from the choosing of export method type. If your shop platform properly calculates taxes and it is possible to retrieve VAT rate and VAT amount per item from the platform the use “Post sale without landed cost method” otherwise use “Post sale with landed cost method”
Post sale without landed cost methods
1. Send order to the system
| End point | /mass-sale/create_post_sale_without_lc_orders |
| Method type |
POST |
| Authorization |
Bearer Authorization token |
| File |
To be provided JSON file with order(s) information. Size of the file should not exceed 50M. |
Order(s) JSON file description
File should contain array of order objects. Each order object should have array of items in order_breakdown attribute.
| JSON | Comments | ||
| { | |||
| "order_list": [ | Required array name | ||
| { | |||
| "order": { | Start of the order object | ||
| "recipient_title": "Mr.", | [ Mr., Ms./Mrs., Dr., Prof ] | ||
| "recipient_first_name": “First name", | Customer first name | ||
| "recipient_last_name": "Last name", | Customer last name | ||
| "delivery_postal_code": "215 60", | Delivery address postal code | ||
| "delivery_city": "Malmö", | Delivery city name | ||
| "delivery_address_line_1": "Tornfalksgatan 1F", | Delivery address line 1 | ||
| "delivery_address_line_2": "", | Delivery address line 2 , might be empty | ||
| "delivery_state_province": "SE", | Delivery state province, might be empty | ||
| "delivery_cost": 20, | Delivery cost including VAT | ||
| "delivery_email": "example@gmail.com", | Customer email | ||
| "delivery_phone": "+35800000", | Customer phone | ||
| "delivery_method": "postal", |
postal or courier If set courier then separate logic for Landed cost calculation will be applied. |
||
| "delivery_country": "SE", | Delivery country ISO 2 alpha code | ||
| "payment_currency": "GBP", | Payment currency ISO 3 alpha code | ||
| "external_order_id": "number_in_the_store", | Order number in the store | ||
| "total_order_amount": 129.96, | Total order amount including all taxes and delivery cost. This value used to verify total order amount computed by EAS solution. Special notice will be provided in the response. | ||
| "is_delivery_to_person": true, | Type of the customer is Company to be set false otherwise true | ||
| "recipient_company_vat": "", | Customer company VAT number | ||
| "recipient_company_name": "", | Customer company name | ||
| "order_breakdown": [ | List of item in the order | ||
| { | |||
| "weight": 0.317465916506464, | Weight to be provided in the unit of measurement set for EM in EAS system (for testing account it is kg, but can be changed on request) | ||
| "item_vat": 11.781, | Total VAT for the line item (price*qty*vat rate) | ||
| "quantity": 4, | Item quantity | ||
| "vat_rate": 12, | VAT rate applied for the item | ||
| "unit_cost": 24.544, | Cost of 1 item without VAT | ||
| "hs6p_received": "", | Harmonized system code for the product, known as HS6 code. If provided empty, system will select it using AI. | ||
| "type_of_goods": "goods", | If item is electronic product (downloadable, tickets …) then need to set TBE | ||
| "long_description": "", | Product long description, might be empty | ||
| "id_provided_by_em": "13253189107965", | Id od the product in the catalog. Should be unique within the order | ||
| "short_description": "HeartMax Capsules", | Short description | ||
| "originating_country": "GB", | Country code where goods were produced (this influence on the customs duties rates) | ||
| "item_delivery_charge": 17.86, |
Delivery cost without VAT If stores platform applies VAT on the delivery cost prorating delivery cost per items amount, then delivery cost should be also prorated in EAS solution. In other case proposing to assign full delivery cost for the first non TBE item.
|
||
| "reduced_tbe_vat_group": false, | If product belong to TBE reduced VAT rate group to be set true | ||
| "act_as_disclosed_agent": false, | If this particular product belong to different seller need to set true. | ||
| "item_delivery_charge_vat": 2.14, | Delivery cost VAT | ||
| "location_warehouse_country": "GB", | Country code of the warehouse from, goods will be dispatched (usually Merchants registration country) | ||
| "seller_registration_country": "GB" | If this particular product belong to different seller need to set this sellers registration Country. | ||
| } | |||
| ] | |||
| }, | |||
| "s10_code": "7987", | Shipping tracking code if available or order number might be used | ||
| "sale_date": "2023-08-17T19:13:29+01:00" | Payment date | ||
| } | |||
| ] | |||
| } |
Response
When request is sent to the system basic validations will be performed and if no errors 200 OK responses in other case 400.
| Response code | Body | Comments |
|---|---|---|
| 200 OK |
{
"job_id": 793,
"message": "Job created successfully"
}
|
|
| 400 bad request |
{
"message": "Error while parsing JSON data:
Unexpected token , in JSON at position 18",
"code": 400,
"type": "CONTACT_ADMIN",
"retryable": false,
"nodeID": "eas-mass-sale-75df5db46f-qjxcg-25"
}
|
message will contain detailed information about error
|
2. Request job status
When JSON file successfully sent to the EAS system need to check job status. If file big enough it will take some time for the system to process it.
| End point | mass-sale/get_post_sale_without_lc_job_status/{job_id} |
| Method type |
GET |
| Authorization |
Bearer Authorization token |
| As a parameter should be used job_id from the 1 step |
Response
| Response code | Body | Comments |
|---|---|---|
| 200 OK |
{ "job_id": 283793, "status": "completed" }
|
Pending → order in the file still processing
completed → all orders processed
|
| 400 bad request |
{ "message": "Job Id not found", "code": 400, "retryable": false, "nodeID": "eas-mass-sale-75df5db46f-qjxcg-25" } |
message will contain detailed information about error
|
3. Request orders processing results
When on the step 2 in response job status is "completed" need to request orders processing results using method
| End point | mass-sale/get_post_sale_without_lc_order_status/{job_id} |
| Method type |
GET |
| Authorization |
Bearer Authorization token |
| As a parameter should be used job_id from the step 1 |
Response
| Response code | Body | Comments |
|---|---|---|
| 200 OK |
{ "job_id": "283793", "order_response_list": [ { "external_order_id": "NLD1006", "status": "successful", "checkout_token": "EAS order JWT token", "message": "order total missmathces" }, { "external_order_id": "NLD1006_test", "status": "rejected", "data": [ { "type": "stringLength", message": "VAT rate not found for delivery country(NL) for item: 13871656763681 - 1000 Design Classics with VAT rate - 91.", "message": "Item VAT rate not found in ref data", "type": "ERR_VALIDATION", nodeID": "eas-mass-sale-75df5db46f-qjxcg-25", action": "calculation.calculatePostSaleWithoutLC" }
] } |
In the response will be provided array of details per each order order provided in the JSON file.
external_order_id order number provided in the JSON file.
Status: successful → order processed and checkout_token should contain valid order JWT token. Content described in the API description for manual connection to EAS system (online VAT calculation) in the JWT Order token description section
Status: rejected → order was not processed, data will contain full description of the error detected. message will contain error description
Content of data will vary from error type
Example:
"data": [
{
"type": "stringLength",
message": "The 'order.order_breakdown[0].location_warehouse_country'
field length must be 2 characters long.",
field": "order.order_breakdown[0].location_warehouse_country",
expected": 2,
actual": 3,
nodeID": "eas-mass-sale-75df5db46f-qjxcg-25",
action": "calculation.calculatePostSaleWithoutLC"
}
]
|
| 400 bad request |
{ "message": "Job Id not found", "code": 400, "retryable": false, "nodeID": "eas-mass-sale-75df5db46f-qjxcg-25" } |
message will contain detailed information about error
|
Post sale with landed cost methods
1. Send order to the system
| End point | /mass-sale/create_mass_post_sale_orders |
| Method type |
POST |
| Authorization |
Bearer Authorization token |
| File |
To be provided JSON file with order(s) information. Size of the file should not exceed 50M. |
Order(s) JSON file description
File should contain array of order objects. Each order object should have array of items in order_breakdown attribute.
| JSON | Comments | ||
| { | |||
| "order_list": [ | Required array name | ||
| { | |||
| "order": { | Start of the order object | ||
| "recipient_title": "Mr.", | [ Mr., Ms./Mrs., Dr., Prof ] | ||
| "recipient_first_name": “First name", | Customer first name | ||
| "recipient_last_name": "Last name", | Customer last name | ||
| "delivery_postal_code": "215 60", | Delivery address postal code | ||
| "delivery_city": "Malmö", | Delivery city name | ||
| "delivery_address_line_1": "Tornfalksgatan 1F", | Delivery address line 1 | ||
| "delivery_address_line_2": "", | Delivery address line 2 , might be empty | ||
| "delivery_state_province": "SE", | Delivery state province, might be empty | ||
| "delivery_cost": 20, | Delivery cost including VAT | ||
| "delivery_email": "example@gmail.com", | Customer email | ||
| "delivery_phone": "+35800000", | Customer phone | ||
| "delivery_method": "postal", |
postal or courier If set courier then separate logic for Landed cost calculation will be applied. |
||
| "delivery_country": "SE", | Delivery country ISO 2 alpha code | ||
| "payment_currency": "GBP", | Payment currency ISO 3 alpha code | ||
| "external_order_id": "number_in_the_store", | Order number in the store | ||
| "total_order_amount": 129.96, | Total order amount including all taxes and delivery cost. This value used to verify total order amount computed by EAS solution. Special notice will be provided in the response. | ||
| "is_delivery_to_person": true, | Type of the customer is Company to be set false otherwise true | ||
| "recipient_company_vat": "", | Customer company VAT number | ||
| "recipient_company_name": "", | Customer company name | ||
| "order_breakdown": [ | Array of order item objects | ||
| { | |||
| "weight": 0.3, | Weight to be provided in the unit of measurement set for EM in EAS system (for testing account it is kg, but can be changed on request) | ||
| "quantity": 4, | Item quantity | ||
| "cost_provided_by_em": 24.544, |
Cost of 1 item including VAT
|
||
| "hs6p_received": "690100", |
Harmonized system code for the product, known as HS6 code. If provided empty, system will select it using AI.
|
||
| "type_of_goods": "goods", | If item is electronic product (downloadable, tickets …) then need to set TBE | ||
| "long_description": "", | Product long description, might be empty | ||
| "id_provided_by_em": "13253189107965", | Id od the product in the catalog. Should be unique within the order | ||
| "short_description": "HeartMax Capsules", | Short description | ||
| "originating_country": "GB", | Country code where goods were produced (this influence on the customs duties rates) | ||
| "reduced_tbe_vat_group": false, | If product belong to TBE reduced VAT rate group to be set true | ||
| "act_as_disclosed_agent": false, | If this particular product belong to different seller need to set true. | ||
| "location_warehouse_country": "GB", | Country code of the warehouse from, goods will be dispatched (usually Merchants registration country) | ||
| "seller_registration_country": "GB" | If this particular product belong to different seller need to set this sellers registration Country. | ||
| } | |||
| ] | |||
| }, | |||
| "s10_code": "7987", | Shipping tracking code if available or order number might be used | ||
| "sale_date": "2023-08-17T19:13:29+01:00" | Payment date | ||
| } | |||
| ] | |||
| } |
Response
When request is sent to the system basic validations will be performed and if no errors 200 OK responses in other case 400.
| Response code | Body | Comments |
|---|---|---|
| 200 OK |
{
"job_id": 793,
"message": "Job created successfully"
}
|
|
| 400 bad request |
{
"message": "Error while parsing JSON data:
Unexpected token , in JSON at position 18",
"code": 400,
"type": "CONTACT_ADMIN",
"retryable": false,
"nodeID": "eas-mass-sale-75df5db46f-qjxcg-25"
}
|
message will contain detailed information about error
|
2. Request job status
When JSON file successfully sent to the EAS system need to check job status. If file big enough it will take some time for the system to process it.
| End point | /mass-sale/get_mass_post_sale_job_status/{job_id} |
| Method type |
GET |
| Authorization |
Bearer Authorization token |
| As a parameter should be used job_id from the 1 step |
Response
| Response code | Body | Comments |
|---|---|---|
| 200 OK |
{ "job_id": 283793, "status": "completed" }
|
Pending → order in the file still processing
completed → all orders processed
|
| 400 bad request |
{ "message": "Job Id not found", "code": 400, "retryable": false, "nodeID": "eas-mass-sale-75df5db46f-qjxcg-25" } |
message will contain detailed information about error
|
3. Request orders processing results
When on the step 2 in response job status is "completed" need to request orders processing results using method
| End point | /mass-sale/get_mass_post_sale_order_status/{job_id} |
| Method type |
GET |
| Authorization |
Bearer Authorization token |
| As a parameter should be used job_id from the step 1 |
Response
| Response code | Body | Comments |
|---|---|---|
| 200 OK |
{ "job_id": "283793", "order_response_list": [ { "external_order_id": "NLD1006", "status": "successful", "checkout_token": "EAS order JWT token", "message": "order total missmathces" }, { "external_order_id": "NLD1006_test", "status": "rejected", "data": [ { "type": "stringLength", message": "VAT rate not found for delivery country(NL) for item: 13871656763681 - 1000 Design Classics with VAT rate - 91.", "message": "Item VAT rate not found in ref data", "type": "ERR_VALIDATION", nodeID": "eas-mass-sale-75df5db46f-qjxcg-25", action": "calculation.calculatePostSaleWithoutLC" }
] } |
In the response will be provided array of details per each order order provided in the JSON file.
external_order_id order number provided in the JSON file.
Status: successful → order processed and checkout_token should contain valid order JWT token. Content described in the API description for manual connection to EAS system (online VAT calculation) in the JWT Order token description section
Status: rejected → order was not processed, data will contain full description of the error detected. message will contain error description
Content of data will vary from error type
Example:
"data": [
{
"type": "stringLength",
message": "The 'order.order_breakdown[0].location_warehouse_country'
field length must be 2 characters long.",
field": "order.order_breakdown[0].location_warehouse_country",
expected": 2,
actual": 3,
nodeID": "eas-mass-sale-75df5db46f-qjxcg-25",
action": "calculation.calculatePostSaleWithoutLC"
}
]
|
| 400 bad request |
{ "message": "Job Id not found", "code": 400, "retryable": false, "nodeID": "eas-mass-sale-75df5db46f-qjxcg-25" } |
message will contain detailed information about error
|
Comments
0 comments
Please sign in to leave a comment.