Currency
Currency codes are always expected in ISO 4217 format. These include commonly used abbreviations such as USD for the United States Dollar, EUR for the Euro, JPY for the Japanese Yen, etc.
Currency values are stored with 2 digits of precision, and are expected to be received with 2 digits of precision. A dollar amount of $12.3412111 will be stored by Corso as $12.34, for example.
Throughout our API's, currencies are represented as strings - e.g. $12.35 will be represented as "12.35". Although there are various approaches used for transmitting currency values, the approach we have chosen allows you the flexibility to parse the values into whatever representation best meets your needs and avoids occasional gotchas between numerical representations of different languages and systems.
Customer vs. Store currency vs. USD
Pricing and cost values are converted between currencies under various scenarios. Understanding the relationship between different currencies and knowing when they are converted can help reduce confusion around the amounts customers should pay for Green Shipping Protection, and around potential billing discrepancies when Corso bills a merchant.
The different currencies that come into play for Green SHipping Protection are the customer currency, the store currency, and USD. These work as follow:
Customer Currency
The Customer Currency is the currency used by the customer at the time they paid for their order. If you operate a store based in Great Britain and all customers checkout using GBP, then the customer currency will be GBP no matter the currency of their bank or card used for payment. If your store accepts payments in different currencies though, you might charge the customer in EUR even though the actual sale value is recorded in your systems as GBP.
Customer Currency is mostly important for displaying values to the customer, especially when a customer needs to process a reorder or a refund. If the customer paid in EUR, we want to display any potential refund amount in EUR, and show their purchase price in EUR.
The customer currency is also used when providing a quote for Shipping Protection. Quotes for Shipping Protection must always have a currency explicitly declared in the request. From our example above, if customers will always pay in GBP no matter the currency of their bank or payment card, then the quoted currency should always be GBP. If you allow the customers to check out in a different currency, you should quote them in that currency.
To maintain consistency, we expect that exchange rate between the customer currency and the store currency to be calculated by you, and transmitted to us with the order.
Store Currency
The store currency is treated as the primary currency in most places throughout the Corso API's. Various money values are sent to Corso on the order for example, and those are all delivered in the base currency of the store. The order total, line item costs, shipping and tax charges, etc. are all expected to be sent to Corso in the store currency.
The store will also be billed by Corso in the store currency.
USD
The cost of GSP, as well as the tiers used to determine that cost, are stored natively in USD. At the time a quote is provided, the cost of the protection is converted from USD to the customer currency (which may also be the store currency). The conversion rate used by Corso is not real-time, but will be no more than 24 hours old.
Because each store ultimately determines how much a customer pays for their shipping protection by setting the price of that variant in the storefront, there may be discrepancies between how much Corso quotes, and how much the customer pays. A merchant should be careful to keep the price of the Green SHipping Protection variants current in their store, to within their acceptable ranges.
While Corso bills in the native currency of the store, we use our stored shipping protection price for billing - NOT the amount actually paid by the customer and reported on the order.