• Version: 1.2.0

Currencies

Currencies represent the various payment currencies that your store accepts. Primarily, currencies are used to convert prices to and from a default custom currency. In Moltin, there are two types of currencies custom and real ones.

Currency flows have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the currency.
code String Yes Yes A standard three-letter code that represents this currency.
title String Yes Yes The full name of this currency.
enabled Choice Yes No Choices available are 0 (Disabled) and 1 (Enabled).
modifier String No No The amount of default currency added or subtracted to all orders using this currency. Should have a + or - before the amount to indicate whether the price is increased or decreased.
exchange_rate Float No No The amount of this custom currency that can be exchanged for one of the default currency.
format String Yes No How prices should be formatted in this currency. Some symbols may have to be passed as hexadecimal codes. For example, “US\u0024{price}”. The “\u0024” sub-string will be rendered as a dollar sign.
decimal_point String No No The character used to separate whole numbers from fractional amounts. By default, this is “.”.
thousand_point String No No The character used to separate the thousands digit from the hundreds digit. By default, this is “,”.
rounding Choice No No Choices are 50 - prices are rounded up above .50, 99 - price are rounded up above .99, or full - prices are not rounded.
default Boolean No No Whether this currency is the default for the store. All exchange rates will be relative to the default currency.
created_at String No No Automatically populated when you create the currency.
updated_at String No No Automatically populated when you modify the currency.

Before using currencies, you’ll need to create them with the https://api.molt.in/v1/currencies endpoint. Currencies can be attached to orders so that prices are converted to the sale currency.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a New Currency

By default, the Moltin API only includes the British Pound (GBP) currency. It has no exchange rate and is default. Every currency that you create must have data for at least the fields marked Required in the table above. You can put data fields in any order.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X POST https://api.molt.in/v1/currencies \
    -H "Authorization: Bearer XXXX" \
    -d "code=USD" \
    -d "title=United States Dollar" \
    -d "enabled=1" \
    -d "format=\u0024{price}"

This call will return a 201 Created HTML status code and the currency information for the newly created currency, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "code":"USD",
    "title":"United States Dollar",
    "enabled":"1",
    "format":"\\u0024{price}",
    "id":"1045136579997204963"
  }
}

The currency actions below will return information in this same format.

Retrieve Currency Information

Once you have created the currencies that you accept as payment, you have two methods to retrieve that information. The first requires that you know the ID number of the currency that you want, and it returns solely the information for that one currency. The second returns an array of all currencies available to your store.

Retrieve a Single Currency by ID

You can GET currency information by appending the currency ID to the currency endpoint. No additional data fields are required.

curl -X GET https://api.molt.in/v1/currencies/:id \
    -H "Authorization: Bearer XXX"

On success, this call returns a 200 OK status and the currency information for the selected ID number.

Retrieve a List of All Currencies

By calling a GET request on the https://api.molt.in/v1/currencies endpoint, you can return an array that contains all of the currencies that you have created.

curl -X GET https://api.molt.in/v1/currencies \
    -H "Authorization: Bearer XXXX"

On success, this call returns 200 OK and an array of currency information, as shown in the Create a Currency section.

Force currency on results

When you are calculating prices, you can pass a non-default currency as a custom X-Currency header and receive prices in that currency. For example, if you set all your prices in US dollars, you can pass the header, “X-Currency GBP” and get a direct conversion of your prices to British Pounds.

You can set the currency header with the SDK by doing the following prior to a request.

$currency = Currency::Set('<CODE>');

Note: The currency selected must be added to your store before available to be switched.

Subsequent requests will mean prices will be returned in the currency specified.

Edit a Currency

To change one or more values in a single currency, use a PUT call with the currencies/{currency ID} endpoint. You can change most field values through this method, including changing a currency from draft to live status, updating exchange rates, or changing the default currency.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X PUT https://api.molt.in/v1/currencies/:id \
    -H "Authorization: Bearer XXXX" \
    -d "exchange_rate=1.01"

On success, this will return 200 OK and the updated currency information.

Delete a Single Currency

To remove a currency, use the same currencies/{ID number} endpoint we used to retrieve a single currency, except we use the DELETE request method.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X DELETE https://api.molt.in/v1/currencies/:id
    -H "Authorization: Bearer XXXX"

If successful, this call will return 200 OK and the following:

{
    "status":true,
    "message":"Currency removed successfully"
}

 Types of currencies

We distinguish between types of currencies based on their code, (e.g. USD, GBP).

Real currencies

Real currencies are currencies that have a currency code that matches a real world currency. The exchange rate for these currencies will be calculated in real time based on real market exchange rate values. Any exchange_rate values you set for a real currency will be ignored.

Note: For the real currencies a custom exchange_rate won’t apply

Custom currencies

Custom currencies are those currencies that don’t match a real world currency. You can specify a custom exchange rate for these currencies using the field exchange_rate. When using custom currencies, totals will be calculated based on the default currency.

We currently support the following real world currencies:

Code Name
AED United Arab Emirates Dirham
AFN Afghan Afghani
ALL Albanian Lek
AMD Armenian Dram
ANG Netherlands Antillean Guilder
AOA Angolan Kwanza
ARS Argentine Peso
AUD Australian Dollar
AWG Aruban Florin
AZN Azerbaijani Manat
BAM Bosnia-Herzegovina Convertible Mark
BBD Barbadian Dollar
BDT Bangladeshi Taka
BGN Bulgarian Lev
BHD Bahraini Dinar
BIF Burundian Franc
BMD Bermudan Dollar
BND Brunei Dollar
BOB Bolivian Boliviano
BRL Brazilian Real
BSD Bahamian Dollar
BTC Bitcoin
BTN Bhutanese Ngultrum
BWP Botswanan Pula
BYR Belarusian Ruble
BZD Belize Dollar
CAD Canadian Dollar
CDF Congolese Franc
CHF Swiss Franc
CLF Chilean Unit of Account (UF)
CLP Chilean Peso
CNY Chinese Yuan
COP Colombian Peso
CRC Costa Rican Colón
CUC Cuban Convertible Peso
CUP Cuban Peso
CVE Cape Verdean Escudo
CZK Czech Republic Koruna
DJF Djiboutian Franc
DKK Danish Krone
DOP Dominican Peso
DZD Algerian Dinar
EEK Estonian Kroon
EGP Egyptian Pound
ERN Eritrean Nakfa
ETB Ethiopian Birr
EUR Euro
FJD Fijian Dollar
FKP Falkland Islands Pound
GBP British Pound Sterling
GEL Georgian Lari
GGP Guernsey Pound
GHS Ghanaian Cedi
GIP Gibraltar Pound
GMD Gambian Dalasi
GNF Guinean Franc
GTQ Guatemalan Quetzal
GYD Guyanaese Dollar
HKD Hong Kong Dollar
HNL Honduran Lempira
HRK Croatian Kuna
HTG Haitian Gourde
HUF Hungarian Forint
IDR Indonesian Rupiah
ILS Israeli New Sheqel
IMP Manx pound
INR Indian Rupee
IQD Iraqi Dinar
IRR Iranian Rial
ISK Icelandic Króna
JEP Jersey Pound
JMD Jamaican Dollar
JOD Jordanian Dinar
JPY Japanese Yen
KES Kenyan Shilling
KGS Kyrgystani Som
KHR Cambodian Riel
KMF Comorian Franc
KPW North Korean Won
KRW South Korean Won
KWD Kuwaiti Dinar
KYD Cayman Islands Dollar
KZT Kazakhstani Tenge
LAK Laotian Kip
LBP Lebanese Pound
LKR Sri Lankan Rupee
LRD Liberian Dollar
LSL Lesotho Loti
LTL Lithuanian Litas
LVL Latvian Lats
LYD Libyan Dinar
MAD Moroccan Dirham
MDL Moldovan Leu
MGA Malagasy Ariary
MKD Macedonian Denar
MMK Myanma Kyat
MNT Mongolian Tugrik
MOP Macanese Pataca
MRO Mauritanian Ouguiya
MTL Maltese Lira
MUR Mauritian Rupee
MVR Maldivian Rufiyaa
MWK Malawian Kwacha
MXN Mexican Peso
MYR Malaysian Ringgit
MZN Mozambican Metical
NAD Namibian Dollar
NGN Nigerian Naira
NIO Nicaraguan Córdoba
NOK Norwegian Krone
NPR Nepalese Rupee
NZD New Zealand Dollar
OMR Omani Rial
PAB Panamanian Balboa
PEN Peruvian Nuevo Sol
PGK Papua New Guinean Kina
PHP Philippine Peso
PKR Pakistani Rupee
PLN Polish Zloty
PYG Paraguayan Guarani
QAR Qatari Rial
RON Romanian Leu
RSD Serbian Dinar
RUB Russian Ruble
RWF Rwandan Franc
SAR Saudi Riyal
SBD Solomon Islands Dollar
SCR Seychellois Rupee
SDG Sudanese Pound
SEK Swedish Krona
SGD Singapore Dollar
SHP Saint Helena Pound
SLL Sierra Leonean Leone
SOS Somali Shilling
SRD Surinamese Dollar
STD São Tomé and Príncipe Dobra
SVC Salvadoran Colón
SYP Syrian Pound
SZL Swazi Lilangeni
THB Thai Baht
TJS Tajikistani Somoni
TMT Turkmenistani Manat
TND Tunisian Dinar
TOP Tongan Paʻanga
TRY Turkish Lira
TTD Trinidad and Tobago Dollar
TWD New Taiwan Dollar
TZS Tanzanian Shilling
UAH Ukrainian Hryvnia
UGX Ugandan Shilling
USD United States Dollar
UYU Uruguayan Peso
UZS Uzbekistan Som
VEF Venezuelan Bolívar Fuerte
VND Vietnamese Dong
VUV Vanuatu Vatu
WST Samoan Tala
XAF CFA Franc BEAC
XAG Silver (troy ounce)
XAU Gold (troy ounce)
XCD East Caribbean Dollar
XDR Special Drawing Rights
XOF CFA Franc BCEAO
XPD Palladium Ounce
XPF CFP Franc
XPT Platinum Ounce
YER Yemeni Rial
ZAR South African Rand
ZMK Zambian Kwacha (pre-2013)
ZMW Zambian Kwacha