Elastic Path Commerce Cloud iOS Swift SDK
A simple to use iOS/tvOS/watchOS SDK to help get you off the ground quickly and efficiently with your Elastic Path Commerce Cloud written in Swift.
Requirements
- iOS 10.0+ / tvOS 10.0+ / watchOS 3.0+
- Swift 4.0+
Installation
Cocoapods
Add the following to your Podfile:
pod 'Moltin', '~> 3.1.2'
Or, quickly try out our examples:
pod try MoltinCarthage
Add the following to your Cartfile:
github "Moltin/ios-sdk" ~> 3.1.2
Swift Package Manager
Add the following to your dependencies value in Package.swift:
dependencies: [
.package(url: "https://github.com/moltin/ios-sdk.git", from: "3.1.2")
]Usage
Making a request
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}
moltin.product.get("<product ID>") { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}
moltin.product.tree { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Checking out & Payment
Paying for a cart is a two step process in Moltin.
First, check out your cart, which will return you an order:
self.moltin.cart.checkout(
cart: ...,
withCustomer: ...,
withBillingAddress: ...,
withShippingAddress: ...) { (result) in
switch result {
case .success(let order):
...
default: break
}
}Now that you have an order, you can pay for your order. Moltin providers several gateways for you to use:
- Stripe
- BrainTree
- Adyen
- Manual
Once you've chosen your payment gateway, you can fulfil one of Moltin's PaymentMethod's:
let paymentMethod = StripeToken(withStripeToken: ...)You can then use this payment method to pay for an order:
self.moltin.cart.pay(
forOrderID: order.id,
withPaymentMethod: paymentMethod) { (result) in
...
}Config
The basic way to set up the Moltin SDK is to create an instance of the Moltin class with your client ID and optionally the locale of the application. However, if you'd like to change additional details of the SDK, such as the URL of your Moltin instance, you can do so by passing in MoltinConfig.
let moltin = Moltin(withClientID: ...) // Takes Locale.currentlet moltin = Moltin(withClientID: ..., withLocale: ...)let config = MoltinConfig(
clientID: ...,
scheme: ...,
host: ...,
version: ...,
locale: ...)
let moltin = Moltin(withConfiguration: config)Or:
let config = MoltinConfig.default(
withClientID: ...,
withLocale: ...)
let moltin = Moltin(withConfiguration: config)Available Resources
- Brands
- Carts
- Categories
- Collections
- Currencies
- Files
- Flows
- Fields
- Entries
- Products
Authentication
Authentication is handled silently for you as part of the SDK. The SDK will cache credentials to ensure that it is not making unnecessary requests.
The iOS SDK only supports Implicit authentication currently.
Filtering
Operations
- Filter
- Sort
- Offset / Limit
- Include
Filter
moltin.product.filter(operator: .eq, key: "name", value: "ProductName").all {
...
}Sort
moltin.product.sort("order").all {
...
}moltin.product.sort("-order").all {
...
}Offset / Limit
moltin.product.limit(10).offset(20).all {
...
}Include
moltin.product.include([.mainImage, .files]).all {
...
}Combining Operations
moltin.product.sort("-name").include([.mainImage]).limit(20).all {
...
}Flows
If you've implemented a custom field on a resource by using flows, you can cast this to a type of your choice by type-hinting your result, so long as this type conforms to Codable:
moltin.product.all { (result: Result<PaginatedResponse<[MyCustomProduct]>>) in
switch result {
case .success(let response):
print(response.data) // [MyCustomProduct]
case .failure(_):
break
}
}moltin.product.get(forID: "<your ID>") { (result: Result<MyCustomProduct>) in
switch result {
case .success(let response):
print(response) // MyCustomProduct
case .failure(_):
break
}We recommend ensuring that your types extend from our base types for safety, then you implement the required init(from decoder: Decoder):
class MyCustomProduct: moltin.Product {
let author: Author
enum ProductCodingKeys : String, CodingKey {
case author
}
required init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: ProductCodingKeys.self)
self.author = try container.decode(Author.self, forKey: .author)
try super.init(from: decoder)
}
}This will allow you to add additional types as you need, but ensures the base type, such as product, is still parsed correctly.
Examples
The Swift SDK is a community-supported software development kit for Elastic Path Commerce Cloud (formerly Moltin). The following examples show you how to use the SDK to make requests to the Commerce Cloud APIs.
For details about the endpoints, objects, and responses, see the Elastic Path Commerce API Reference.
Basics
Includes
Examples of using include with resources. For more information, see Includes.
Include category products
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.category.include([.products]).get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Include product main_image
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.product.include([.main_image]).all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Multiple includes
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.product.include([.main_image, .category]).all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Pagination
Examples of using pagination with resources. For more information, see Pagination.
Get all categories, two per page
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.limit(2).all {
// Do something
}Get products 21-30
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.limit(10).offset(20).all {
// Do something
}Filtering
Examples of using different filter operators. For more information, see Filtering.
The eq operator
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .eq, key: "commodity_type", value: "digital").all {
// Do something
}The like operator - A string begins with a specified value
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .like, key: "sku", value: "SHOE_DECK_*").all {
// Do something
}The like operator - A string contains a specified value
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .like, key: "sku", value: "*_DECK_*").all {
// Do something
}The like operator - A string ends with a specified value
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .like, key: "sku", value: "*_RED").all {
// Do something
}Chaining multiple operators
Caution: This feature is currently in Beta and you should expect it to change.
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product
.filter(operator: .eq, key: "commodity_type", value: "physical")
.sort("created_at")
.all {
// Do something
}Sorting
Examples of using sort with resources. For more information, see Sorting.
Sort products by created_at in ascending order
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.sort("created_at").all {
// Do something
}Sort products by created_at in descending order
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.sort("-created_at").all {
// Do something
}Tokens
Get an implicit access token
An implicit token can be thought of as a Read only token.
let moltin = Moltin(withClientID: "<your client ID>")Currency
Get a currency
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.currency.get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Get all currencies
let moltin = Moltin(withClientID: "<your client ID>")
moltin.currency.all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Products
Get all products
let moltin = Moltin(withClientID: "<your client ID>")
self.moltin.product.include([.mainImage]).all { (result: Result<PaginatedResponse<[moltin.Product]>>) in
switch result {
case .success(let response):
DispatchQueue.main.async {
self.products = response.data ?? []
}
case .failure(let error):
print("Products error", error)
}
}
}Get all products that belong to a category
let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .eq, key: "category.id", value: "xxxx").all {
response in
// Do something
}Get a product
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.product.get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Brands
Get all brands
let moltin = Moltin(withClientID: "<your client ID>")
moltin.brand.all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Get a brand
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.brand.get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Categories
Get all categories
let moltin = Moltin(withClientID: "<your client ID>")
moltin.category.all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Get a category
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.category.get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Get the categories tree
let moltin = Moltin(withClientID: "<your client ID>")
moltin.category.tree { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Collections
Get all collections
let moltin = Moltin(withClientID: "<your client ID>")
moltin.collection.all { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Get a collection
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.collection.get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Carts
Get a cart
let moltin = Moltin(withClientID: "<your client ID>")
self.moltin.cart.get(forID: AppDelegate.cartID, completionHandler: { (result) in
switch result {
case .success(let result):
DispatchQueue.main.async {
print("Cart:", result)
}
case .failure(let error):
print("Cart error:", error)
}
})Get cart items
let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
self.moltin.cart.items(forCartID: referenceId) { (result) in
switch result {
case .success(let result):
DispatchQueue.main.async {
print("Cart items:", result.data)
}
case .failure(let error):
print("Cart error:", error)
}
}
}Add a product to a cart
let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
let productId = 'XXXX'
let productQty = 'XXXX'
self.moltin.cart.addProduct(withID: productId , ofQuantity: productQty, toCart: referenceId, completionHandler: { (_) in
})Add a promotion to a cart
let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
self.moltin.cart.addPromotion(code, toCart: referenceId) { (result) in
switch result {
case .success(let status):
DispatchQueue.main.async {
print("Promotion: (status)")
}
default: break
}
}
}Check out a cart
let moltin = Moltin(withClientID: "<your client ID>")
moltin.cart.checkout(
cart: ...,
withCustomer: ...,
withBillingAddress: ...,
withShippingAddress: ...) { (result) in
switch result {
case .success(let order):
...
default: break
}
}Delete a cart
let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
self.moltin.cart.deleteCart(referenceId, completionHandler: { (result) in
switch result {
case .success(let result):
print("Cart error:", result)
case .failure(let error):
print("Cart error:", error)
}
})Customers
Get a customer
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.customer.get(forID: id) { result in
switch result {
case .success(let response):
print(response)
case .failure(let error):
print(error)
}
}Payments
Create a Stripe payment
let moltin = Moltin(withClientID: "<your client ID>")
let paymentMethod = StripeToken(withStripeToken: ...)
moltin.cart.pay(
forOrderID: order.id,
withPaymentMethod: paymentMethod) { (result) in
...
}Create a manually authorize payment
let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
let paymentMethod = ManuallyAuthorizePayment()
moltin.cart.pay(forOrderID: order.id, withPaymentMethod: paymentMethod) { (result) in
switch result {
case .success:
print("Success")
case .failure(let error):
print(error)
}
}Further Documentation
Find more general documentation on the API docs.
Communication
- If you need help with the SDK or the platform, get in touch on the forum
- If you found a bug with the SDK, open an issue on GitHub
- If you have a feature request for the SDK, open an issue.
- If you want to contribute to the SDK, submit a pull request.
License
Moltin is available under the MIT license. See the LICENSE file for more info.