Allow id and email identifiers to be updated when cio_id specified

README.md

@@ -77,7 +77,7 @@ if you pass along the current subscription plan (free / basic / premium) for you
 set up triggers which are only sent to customers who have subscribed to a
 particular plan (e.g. "premium").
 
-You'll want to indentify your customers when they sign up for your app and any time their
+You'll want to identify your customers when they sign up for your app and any time their
 key information changes. This keeps [Customer.io](https://customer.io) up to date with your customer information.
 
 ```ruby
@@ -95,6 +95,24 @@ $customerio.identify(
 )
 ```
 
+### Updating customers
+
+You can use the identify operation to update customers.
+If you need to change the `id` or `email` identifiers for a customer,
+you will need to pass in the `cio_id` identifier.
+`cio_id` is a unique identifier set by Customer.io, used to reference a person,
+and cannot be changed.
+
+E.g.: if the customer created in the identify operation above was given the `cio_id` of `"f000000d"`, you could change its ID and email address using:
+
+```ruby
+$customerio.identify(
+  :cio_id => "f000000d",
+  :id => 1005,
+  :email => "bob.fullname@example.com"
+)
+```
+
 ### Deleting customers
 
 Deleting a customer will remove them, and all their information from

lib/customerio/client.rb

@@ -151,9 +151,17 @@ def merge_customers_path
 
     def create_or_update(attributes = {})
       attributes = Hash[attributes.map { |(k,v)| [ k.to_sym, v ] }]
-      raise MissingIdAttributeError.new("Must provide a customer id") if is_empty?(attributes[:id])
+      if is_empty?(attributes[:id]) && is_empty?(attributes[:cio_id])
+        raise MissingIdAttributeError.new("Must provide a customer id")
+      end
 
-      url = customer_path(attributes[:id])
+      # Use cio_id as the identifier, as present,
+      # to allow the id and email identifiers to be updated.
+      customer_id = attributes[:id]
+      if !is_empty?(attributes[:cio_id])
+        customer_id = "cio_" + attributes[:cio_id]
+      end
+      url = customer_path(customer_id)
       @client.request_and_verify_response(:put, url, attributes)
     end
 

spec/client_spec.rb

@@ -172,6 +172,7 @@ def json(data)
     it "requires an id attribute" do
       lambda { client.identify(email: "customer@example.com") }.should raise_error(Customerio::Client::MissingIdAttributeError)
       lambda { client.identify(id: "") }.should raise_error(Customerio::Client::MissingIdAttributeError)
+      lambda { client.identify(cio_id: "") }.should raise_error(Customerio::Client::MissingIdAttributeError)
     end
 
     it 'should not raise errors when attribute keys are strings' do
@@ -183,6 +184,45 @@ def json(data)
 
       lambda { client.identify(attributes) }.should_not raise_error()
     end
+
+    it 'uses cio_id for customer id, when present, for id updates' do
+      stub_request(:put, api_uri('/api/v1/customers/cio_347f00d')).with(
+        body: {
+          cio_id: "347f00d",
+          id: 5
+        }).to_return(status: 200, body: "", headers: {})
+
+      client.identify({
+        cio_id: "347f00d",
+        id: 5
+      })
+    end
+
+    it 'uses cio_id for customer id, when present, for email updates' do
+      stub_request(:put, api_uri('/api/v1/customers/cio_347f00d')).with(
+        body: {
+          cio_id: "347f00d",
+          email: "different.customer@example.com"
+        }).to_return(status: 200, body: "", headers: {})
+
+      client.identify({
+        cio_id: "347f00d",
+        email: "different.customer@example.com"
+      })
+    end
+
+    it 'allows updates with cio_id as the only id' do
+      stub_request(:put, api_uri('/api/v1/customers/cio_347f00d')).with(
+        body: {
+          cio_id: "347f00d",
+          location: "here"
+        }).to_return(status: 200, body: "", headers: {})
+
+      client.identify({
+        cio_id: "347f00d",
+        location: "here"
+      })
+    end
   end
 
   describe "#delete" do