Migrating a Two Tap API integration to support international orders
This blog post is a technical followup on the Two Tap Cross-Border launch. You should read the announcement before continuing.
If you are using our Whitelabel Cart or Instant, you don’t need to do anything, but you might still want to read below to understand a couple of differences between domestic and international ordering.
In domestic and pickup-from-store orders Two Tap sends all the information to the retailer to be processed. That means the end retailer (let’s say Kohl’s) processes the payment, handles returns, customer support, and is the merchant of record. This is what we call the pass-through method.
For international orders, this all changes. The end customer (let’s say in Japan) buys the products from Two Tap, which are then, in the background, automatically purchased by Two Tap from the retailer and shipped to a US warehouse. This means Two Tap processes the consumer payment, handles returns, customer support, and is the merchant of record.
For international orders Two Tap provides more flexibility:
- A larger number of payment methods will be supported. For instance: Apple Pay, Android Pay. (coming soon)
- The CVV code will not be required after an initial purchase. (coming soon)
- Publisher discounts (eg. a publisher wanting to fund $10 off offers).
- One international landed cost for the whole cart. Shipping prices are more affordable as Two Tap consolidates products into one box and ships them overseas in one international flight.
- Estimation guarantees. If Two Tap’s estimation is wrong, Two Tap will eat the cost.
The international app approval process is a bit more thorough, and all apps must show the “Two Tap INTL ToS Approval Box”.
/cart, /cart/status, /cart/estimates now accept a ‘destination_country’.
‘destination_country’ changes prices and currencies dynamically. Please keep in mind that if you run /cart/estimates without an address or destination_country and Two Tap returns some prices in USD, those might change completely when you run /purchase with a Japanese address. Make sure you are showing the consumer the right estimates.
estimates and sites[id][prices] not available for international orders
In /cart/estimates and /purchase/status Two Tap used to return the prices broken down by site_id. For instances, $150 final price at Kohls, and $200 final price at eBags. For domestic orders this doesn’t change.
Today we are introducing two new fields: estimated_total_prices for /cart/estimates, and total_prices for /purchase/status. Here you will find the total values for the whole cart.
They way we handled this API change on our Cart is that we show the ‘estimated_total_prices’ on the cart review page, for both domestic and international orders. We also added an extra option on domestic orders to ‘view a breakdown of prices by store’.
http_finished_url is gone, meet http_update_url
‘http_update_url’ is called after a purchase changes state. State are: ‘pending’, ‘info_running’, ‘info_finished’, ‘confirm_running’, ‘confirm_finished’, ‘waiting_for_tracking_links’, ‘to_warehouse’, ‘to_shopper’, ‘done’, and ‘cancelled’.
For domestic purchases a purchase changes state after injection or when a change happens in the ‘sites[site_id][remote_status]’ /purchase/status fields. Yes, Two Tap is slowly starting to monitor purchases after they’ve been injected, and will send you updates as they happen.
For international purchases, this means a change in a new ‘status’ /purchase/status field.
The information sent is the same as in the /purchase/status API method.
Available shipping countries
The available shipping countries are sent with /cart/status inside the sites[id][shipping_countries_support] field.
These are all the changes you need to know about. Feel free to contact us with any questions.