Examples¶
Below are a series of examples of how to do common tasks using sharpy.
Customers¶
Creation¶
Customer creation is generally just a simple call on a product instance. The
CheddarProduct.create_customer()
method supports everything that the Cheddar Getter API
add customer call
supports.
Free Customers¶
Free customers require a minimal amount of information. Accordingly, the call to create them is pretty simple.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Create the customer
customer = product.create_customer(
code = 'cust-id-1', # An unique identifier for the customer
first_name = 'Philip',
last_name = 'Fry',
email = 'pfry@planetexpress.com',
plan_code = 'FREE_MONTHLY', # The code for plan to subscribe the customer to
)
|
Paypal Customers¶
Paypal customers require only a little bit more information. You ask CheddarGetter to create the account, then redirect the user to the Paypal site to log in and authorize the subscription.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Create the customer
customer = product.create_customer(
code = 'cust-id-2',
first_name = 'Turanga',
last_name = 'Leela',
email = 'tleela@planetexpress.com',
plan_code = 'PAID_MONTHLY',
method = 'paypal',
cc_first_name = 'Hubert',
cc_last_name = 'Farnsworth',
return_url = 'https://www.planetexpress.com/thanks/cust-id-2/',
cancel_url = 'https://www.planetexpress.com/sorry/cust-id-2/',
)
# redirect the user to the Paypal site to authorize the subscription
redirect(
customer.subscriptions[0].redirect_url,
)
|
When the user has accepted or cancelled the subscription they will be redirected to the URLs passed into the creation call. You should always verify the status of the account with CheddarGetter directly, rather than relying on the user visiting those URLs.
Paid Customers¶
Paid customers require a bit more information, but still are fairly easy to create.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Create the customer
customer = product.create_customer(
code = 'cust-id-2',
first_name = 'Turanga',
last_name = 'Leela',
email = 'tleela@planetexpress.com',
plan_code = 'PAID_MONTHLY',
cc_number = '4111111111111111',
cc_expiration = '03/3012',
cc_card_code = '123',
cc_first_name = 'Hubert',
cc_last_name = 'Farnsworth',
cc_address = '1 πth Ave.',
cc_city = 'New New York',
cc_state = 'New York',
cc_zip = '10001',
)
|
Customers With Optional Info¶
Cheddar has a number of optional fields which they accept when creating a
customer. Most of these fields are simply provided to help you keep track
of customer info, but some of the fields (e.g. initial_bill_date
) can
affect Cheddar Getter’s behavior. Check out Cheddar Getter’s API docs for more details on specific optional fields.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | from datetime import datetime, timedelta
from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Set a intitial bill date in the future to provide a free trial
bill_date = datetime.now() + timedelta(days=60)
# Create the customer
customer = product.create_customer(
# Required fields
code = 'cust-id-3',
first_name = 'Hermes',
last_name = 'Conrad',
email = 'hconrad@planetexpress.com',
plan_code = 'PAID_MONTHLY',
cc_number = '4111111111111111',
cc_expiration = '03/3012',
cc_card_code = '123',
cc_first_name = 'Hubert',
cc_last_name = 'Farnsworth',
cc_address = '1 πth Ave.',
cc_city = 'New New York',
cc_state = 'New York',
cc_zip = '10001',
# Optional Fields
initial_bill_date = bill_date,
referer = 'http://www.momsfriendlyrobots.com/',
)
|
Note
Notice that the initial_bill_date is provided as a datetime
object. Sharpy always expects and returns the best python native data
structure for a given piece of information. That being said, sharpy is
generally pretty flexible about what forms of data it will take in.
Customers With Tracked Items¶
Depending on your pricing model, you may want to create customers as having already consumed tracked items. Fortunately, Cheddar Getter’s API allows us to provide tracked item information as part of the create customer call. While you can always report on tracked items with their own API calls, reporting tracked item usage as part of customer creation saves a potentially slow request/response cycle and avoids possible error states where a create customer call succeeds but subsequent API calls fail.
To create a customer with tracked item information, all you need to do is pass
in a collection of dictionaries to the items
parameter of the
CheddarProduct.create_customer()
which describe the desired
item info.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Describe item use
items = [
{'code': 'poplers', 'quantity': '1000'},
{'code': 'dark matter balls'},
]
# Create the customer
customer = product.create_customer(
code = 'cust-id-3',
first_name = 'Turanga',
last_name = 'Leela',
email = 'tleela@planetexpress.com',
plan_code = 'PAID_MONTHLY',
cc_number = '4111111111111111',
cc_expiration = '03/3012',
cc_card_code = '123',
cc_first_name = 'Hubert',
cc_last_name = 'Farnsworth',
cc_address = '1 πth Ave.',
cc_city = 'New New York',
cc_state = 'New York',
cc_zip = '10001',
items = items,
)
|
Notice here that the quantity
value of the item dictionary is optional.
If you don’t include a quantity
value, sharpy assumes a quantity of 1
.
Customers With Custom Charges¶
Similar to creating customers with tracked items, the Cheddar Getter API
allows you to provide custom charge information as part of the create customer
call. Doing so saves a request to the API and eliminates the risk of
customers getting created without the desired charges. Just like with
tracked items, you provide charge information by building a collection
of dictionaries and passing that collection to the charges
parameter
of CheddarProduct.create_customer()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | from decimal import Decimal
from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Describe item use
charges = [
{
'code': 'Senior Discount',
'quantity': '2',
'each_amount': Decimal('-10.21'),
'description': "A discount for every half-centry of the customer's age"
},
{
'code': 'Mom Tax',
'each_amount': 200,
},
]
# Create the customer
customer = product.create_customer(
code = 'cust-id-3',
first_name = 'Turanga',
last_name = 'Leela',
email = 'tleela@planetexpress.com',
plan_code = 'PAID_MONTHLY',
cc_number = '4111111111111111',
cc_expiration = '03/3012',
cc_card_code = '123',
cc_first_name = 'Hubert',
cc_last_name = 'Farnsworth',
cc_address = '1 πth Ave.',
cc_city = 'New New York',
cc_state = 'New York',
cc_zip = '10001',
charges = charges,
)
|
A few things to notice here:
- Quantity is optional and will be assumed to be
1
if not provided.- Description is optional and will be assumed to be
""
.- Each amount can be of any type which can be cast to Decimal.
- Negative values for
each_amount
are credits to the customer’s account, positive values are charges.
Fetching¶
Get an individual customer¶
To fetch the information for an individual customer, simply call
CheddarProduct.get_customer()
with your customer’s code. The
customer’s code is the unique identifier you provided in your customer
creation call.
from sharpy.product import CheddarProduct
from sharpy import exceptions
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
try:
# Get the customer from Cheddar Getter
customer = product.get_customer(code='1BDI')
except exceptions.NotFound, err:
print 'You do not appear to be a customer yet'
else:
# Test if the customer's subscription is canceled
if customer.subscription.canceled:
if customer.subscription.cancel_type == 'paypal-pending':
print 'Waiting for Paypal authorization'
else:
print 'Your subscription appears to have been cancelled'
else:
print 'Your subscription appears to be active'
If a customer with the given code cannot be found, a
sharpy.exceptions.NotFound
exception will be raised.
Get all customers¶
from sharpy.product import CheddarProduct
# Get a product instance to work with
product = CheddarProduct(
username = CHEDDAR_USERNAME,
password = CHEDDAR_PASSWORD,
product_code = CHEDDAR_PRODUCT,
)
# Get the customer from Cheddar Getter
customers = product.get_customers()
Hosted Updates¶
CheddarGetter has a “hosted” solution that allows you to get up and running quickly. This solution allows you to direct the customer to a CheddarGetter-hosted site to sign up. Once signed up, you need to be able to send the customer back to the correct account to modify their subscriptions. To do this, you need to calculate a CheddarGetter key for the account.
import hashlib, urllib
key = hashlib.md5( '%s|%s'%( customer_code, CHEDDAR_PRODUCT_KEY, )).hexdigest()[:10]
query = urllib.urlencode({
'code': customer_code,
'key': key,
})
redirect(
CHEDDAR_HOSTED_DOMAIN + '/update' + '?' + query
)