Customers

Centrally manage customer data including contact information, shipping addresses, and payment methods. Create customer profiles to reuse information across checkouts, save payment methods for future purchases, and track customers more easily.

See API Reference for complete endpoint documentation.

Customer Management

You can create, update, and manage customer profiles with basic information like email, name, and phone number. Key points:

• Email is immutable: Once set, a customer's email cannot be changed
• Unique identifier: Email serves as the primary way to identify customers
• Soft deletion: Customers are marked as deleted but historical data is preserved

Address Management

Each customer can have multiple shipping addresses. You can:

• Add multiple addresses for different shipping destinations
• Set a default address that's automatically used in checkouts
• Update existing addresses rather than creating duplicates
• US addresses only (international support coming soon)

Key address fields include street address, city, state, postal code, and country.

Payment Method Management

Payment methods are tokenized credit cards associated with a customer. The actual card data is stored securely (see Tokenizing Credit Cards) - only the token is linked to the customer.

How Payment Methods Work

Payment methods are created through the credit card tokenization flow:

1. Customer tokenizes their card using the playground or SDK (see Tokenizing Credit Cards)
2. You receive a token like cct_sandbox_xyz123
3. Use the token in checkouts and it automatically associates with the customer
4. Set as default so future checkouts can use it without specifying

Payment methods are identified by their credit_card_token (e.g., cct_sandbox_xyz123).

Managing Payment Methods

You can:

• List saved payment methods for a customer
• Set a default payment method for automatic use in checkouts
• Remove payment methods when no longer needed
• Add labels like "Personal Visa" or "Business Mastercard" for easy identification

Note: Payment methods are created implicitly when a credit_card_token is used in a checkout with a customer_id. There is no direct "create payment method" endpoint - instead, tokenize a card using the methods described in Tokenizing Credit Cards.

Complete Example

Here's a full workflow showing customer creation, address management, payment setup, and checkout:

import requests

api_key = "YOUR_API_KEY"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# 1. Create a customer
customer = requests.post(
    "https://api.simplecheckout.ai/v0/customers",
    headers=headers,
    json={
        "email": "[email protected]",
        "name": "John Doe",
        "phone": "+1234567890"
    }
).json()

customer_id = customer["id"]
print(f"Created customer: {customer_id}")

# 2. Add a shipping address
address = requests.post(
    f"https://api.simplecheckout.ai/v0/customers/{customer_id}/addresses",
    headers=headers,
    json={
        "line1": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "postal_code": "78701",
        "country": "US"
    }
).json()

address_id = address["id"]
print(f"Created address: {address_id}")

# 3. Set as default address
requests.patch(
    f"https://api.simplecheckout.ai/v0/customers/{customer_id}/addresses/{address_id}/default",
    headers=headers
)
print("Set as default address")

# 4. Customer tokenizes their card (via playground or SDK)
# This happens in your frontend - see "Tokenizing Credit Cards" guide
credit_card_token = "cct_sandbox_xyz123"  # Received from tokenization

# 5. Use saved payment method as default
requests.patch(
    f"https://api.simplecheckout.ai/v0/customers/{customer_id}/payment-methods/{credit_card_token}/default",
    headers=headers
)
print("Set default payment method")

# 6. Create checkout using customer reference
checkout = requests.post(
    "https://api.simplecheckout.ai/v0/checkouts",
    headers=headers,
    json={
        "url": "https://buy.stripe.com/test_example",
        "customer_id": customer_id
        # No need to specify address_id or credit_card_token - defaults will be used
    }
).json()

print(f"Created checkout: {checkout['id']}")
print(f"Customer: {checkout.get('display_name')}")

# 7. For next purchase, even simpler - just reference the customer
next_checkout = requests.post(
    "https://api.simplecheckout.ai/v0/checkouts",
    headers=headers,
    json={
        "url": "https://buy.stripe.com/test_another_product",
        "customer_id": customer_id
    }
).json()

print(f"Next checkout: {next_checkout['id']}")

Best Practices

Customer Email

• Email is immutable: Once a customer is created, the email cannot be changed
• To change email: Create a new customer with the new email address
• Use as unique identifier: Email serves as the primary identifier for customers

Address Management

• Set defaults: Mark one address as default for seamless checkouts
• US only (for now): Currently only US addresses are supported
• Keep them updated: Update addresses rather than creating duplicates
• Multiple addresses: Customers can have multiple addresses for different shipping needs

Payment Methods

• Created via tokenization: Payment methods are added by tokenizing cards (see Tokenizing Credit Cards)
• Automatic association: When you use a credit_card_token with a customer_id in a checkout, it automatically associates with that customer
• Set defaults: Mark one as default so customers don't need to select it each time
• Labels help: Add descriptive labels like "Personal Visa" or "Business Mastercard"

Using with Checkouts

• Simple checkouts: Just pass customer_id - defaults will be used
• Override defaults: Specify address_id or credit_card_token to use non-default options
• Display names: Checkouts will show display_name (typically email) for easy tracking
• Mix and match: You can use customer_id for contact info but override address or payment

What's Next?

• Checkouts - Process purchases with customer data
• Tokenizing Credit Cards - Securely collect payment information