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
)

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

# 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
customer = product.get_customer(code='1BDI')

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()

Project Versions

Table Of Contents

Previous topic

Sharpy

Next topic

High Level API

This Page