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.

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
)