Sales & Orders

​

Overview

​

Purchase States

​

Normal Purchase Flow

​

State Definitions

​

Subscription Purchase States

• not_charged - Free trial or plan upgrade (no payment)
• is_original_subscription_purchase - Template for recurring charges
• is_free_trial_purchase - First charge after trial period

​

Gift Purchase States

1. Gifter Purchase - Standard successful purchase
2. Giftee Purchase - gift_receiver_purchase_successful (always $0)

​

Purchase Lifecycle

​

Creating a Purchase

​

Processing a Purchase

# Purchase processing workflow
purchase.process! # Handles payment processing
  → prepare_chargeable # Set up payment method
  → charge_card # Execute payment
  → mark_successful! # Transition state
  → create_artifacts_and_send_receipt! # Deliver product

​

After Successful Purchase

1. Artifact Creation
   • Generate URL redirects for file downloads
   • Create license keys (if enabled)
   • Set up media locations
   • Generate PDF stamps
2. Customer Communication
   • Send purchase receipt email
   • Deliver downloadable content
   • Send to Discord/integrations
3. Seller Notifications
   • Email notification of sale
   • Webhook POST to configured URLs
   • Update analytics and metrics
4. Affiliate Credits
   • Calculate affiliate commission
   • Create affiliate credit record
   • Notify affiliate of sale

​

Sales Management

​

Viewing Sales

​

Sales Search Options

// Active sales search (for customer count)
{
  state: ["successful", "not_charged"],
  exclude_refunded_except_subscriptions: true,
  exclude_unreversed_chargedback: true,
  exclude_non_original_subscription_purchases: true,
  exclude_bundle_product_purchases: true
}

// Charged sales search (for revenue)
{
  state: ["successful", "preorder_authorization_successful"],
  exclude_giftees: true,
  exclude_refunded: true,
  exclude_unreversed_chargedback: true
}

​

Purchase Information

​

Core Purchase Data

• Product name and ID
• Variant selection
• Quantity purchased
• Rental vs. purchase flag

• Price cents (product price)
• Total transaction cents (what buyer paid)
• Tax cents (seller-collected tax)
• Gumroad tax cents (VAT, GST)
• Fee cents (platform fees)
• Affiliate credit cents

• Email address
• Full name
• Shipping address (if physical)
• IP address and country
• Browser fingerprint (GUID)

• Credit card fingerprint
• Payment processor (Stripe, PayPal)
• Currency used
• Offer code applied
• Subscription ID (if recurring)

​

Refunds

​

Processing Refunds

# Full refund
purchase.refund!(amount: purchase.price_cents)

# Partial refund
purchase.refund!(amount: 1000) # $10.00

​

Refund Logic

1. Stripe Refund - Payment processor refund initiated
2. Fee Handling - Platform fees typically waived
3. Affiliate Credits - Create negative affiliate credit
4. Balance Adjustment - Update seller balance
5. Customer Notification - Send refund confirmation

​

Refund Policies

• Product-level policies - Specific terms per product
• Account-level policies - Apply to all products
• Time-based windows - E.g., “30-day money-back guarantee”
• No questions asked - Automatic approval

​

Chargebacks

​

Chargeback Workflow

1. Notification - Webhook alert of chargeback
2. Evidence Period - Submit evidence to contest
3. Resolution - Won, lost, or reversed
4. Balance Impact - Deducted from seller balance

​

Chargeback Fields

• chargeback_date - When chargeback occurred
• chargeback_reason - Dispute reason code
• chargeback_reversed - Won the dispute

​

Order Management

​

Order Structure

// An order contains multiple line items
Order {
  id: "order_abc123",
  purchases: [
    { product: "Product A", price: 2900 },
    { product: "Product B", price: 4900 }
  ],
  total: 7800
}

​

Multi-Product Checkout

• Cart functionality for buying multiple products
• Combined payment processing
• Single receipt for all items
• Shared shipping (for physical items)

​

Shipping Management

​

Shipment Workflow

1. Purchase Created - Collect shipping address
2. Prepare Shipment - Package items
3. Mark as Shipped - Add tracking number
4. Customer Notification - Send tracking email
5. Delivery Confirmation - Update status

​

Shipment Information

purchase.create_shipment!(
  tracking_number: "1Z999AA10123456784",
  carrier: "UPS",
  shipped_at: Time.current
)

​

Custom Fields

​

Field Types

• Text Input - Single line text
• Textarea - Multi-line text
• Dropdown - Select from options
• Checkbox - Boolean yes/no

​

Field Configuration

• Global Fields - Apply to all products
• Product Fields - Specific to one product
• Required vs. Optional
• Per-product collection - For multiple quantities

​

Use Cases

​

License Keys

​

License Generation

# License key format
{purchase_id}-{random_hash}
# Example: "ABC12345-9K8L7M6N5P4Q"

​

License Features

• Verification API - Check if key is valid
• Usage Limits - Track activations
• Multi-seat Licenses - Quantity-based licensing
• License Rotation - Generate new keys
• Disable/Enable - Revoke access remotely

​

License Management

# Verify a license
POST /v2/licenses/verify
{ license_key: "ABC12345-9K8L7M6N5P4Q" }

# Decrement uses
PUT /v2/licenses/decrement_uses_count
{ license_key: "ABC12345-9K8L7M6N5P4Q" }

​

Sales Analytics

​

Key Metrics

​

Revenue Breakdown

# Understanding the money flow
Total Transaction: $100.00 (what customer paid)
  - Product Price: $90.00
  - Tax (seller remits): $5.00
  - VAT (Gumroad remits): $5.00

Seller Receives: $80.10
  - Product Price: $90.00
  - Less Gumroad Fee (10%): -$9.00
  - Less Processor Fee (2.9% + $0.30): -$0.90

​

Transaction Fees

• Standard: 10% of transaction
• Discover boost: Additional 10% for promoted sales
• Affiliate commission: Variable percentage

• Credit card: 2.9% + $0.30
• PayPal: Similar to credit card rates
• Varies by country and currency

​

Export and Reporting

​

Sales Export

# Export all sales
GET /purchases/export

# With filters
GET /purchases/export?start_time=2024-01-01&end_time=2024-12-31

​

Export Fields

• Sale date and time
• Customer information
• Product details
• Pricing and fees
• Refund status
• Custom field values

​

Fraud Prevention

​

Automatic Protections

• Card testing prevention - Block rapid failed attempts
• Velocity checks - Limit purchases per card/IP
• Browser fingerprinting - Track suspicious patterns
• Geographic analysis - Flag unusual locations
• Risk scoring - Machine learning risk assessment

​

Manual Controls

• Block specific emails - Ban abusive customers
• Block IP addresses - Geographic restrictions
• Hold purchases - Manual review before delivery
• Refund and ban - Remove fraudulent buyers

​

Customer Communication

​

Receipts

• Purchase confirmation email
• Product download links
• Order details and pricing
• License keys (if applicable)
• Custom receipt text from seller

​

Receipt Management

# Resend receipt
purchase.resend_receipt

# View receipt URL
receipt_purchase_url(purchase.external_id)

​

Contact Preferences

• can_contact - Opt-in for marketing emails
• Unsubscribe links in all emails
• Separate transactional vs. marketing

​

API Access

// Get all sales
GET /v2/sales

// Get specific sale
GET /v2/sales/:id

// Filter sales
GET /v2/sales?product_id=abc123&after=2024-01-01

​

Webhooks

{
  "sale": {
  "id": "abc123",
    "product_name": "My Product",
    "email": "[email protected]",
    "price": 2900,
    "currency": "usd",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​

Best Practices

​

Next Steps