Skip to main content

cURL Examples

This guide provides comprehensive cURL examples for interacting with the Azotte API directly. These examples are useful for testing, debugging, and integration scenarios where SDKs are not available.

Authentication​

API Key Authentication​

All API requests require authentication using your secret API key in the Authorization header:

curl https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

Tenant Context​

For multi-tenant applications, include the tenant ID:

curl https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Tenant-ID: tenant_123" \
  -H "Content-Type: application/json"

Customer Management​

Create Customer​

curl https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "metadata": {
      "source": "website",
      "campaign": "summer_2024"
    },
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  }'

Retrieve Customer​

# Get customer by ID
curl https://api.azotte.com/v1/customers/cus_123 \
  -H "Authorization: Bearer sk_live_..."

# Get customer with expanded data
curl "https://api.azotte.com/v1/customers/cus_123?expand[]=subscriptions&expand[]=payment_methods" \
  -H "Authorization: Bearer sk_live_..."

Update Customer​

curl https://api.azotte.com/v1/customers/cus_123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "name": "John Smith",
    "email": "john.smith@example.com",
    "metadata": {
      "updated_at": "2024-01-15"
    }
  }'

List Customers​

# Basic listing
curl "https://api.azotte.com/v1/customers?limit=10" \
  -H "Authorization: Bearer sk_live_..."

# With filters
curl "https://api.azotte.com/v1/customers?created[gte]=2024-01-01&email[contains]=@company.com&limit=50" \
  -H "Authorization: Bearer sk_live_..."

# Pagination
curl "https://api.azotte.com/v1/customers?starting_after=cus_last_id&limit=100" \
  -H "Authorization: Bearer sk_live_..."

Delete Customer​

curl https://api.azotte.com/v1/customers/cus_123 \
  -H "Authorization: Bearer sk_live_..." \
  -X DELETE

Subscription Management​

Create Subscription​

curl https://api.azotte.com/v1/subscriptions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "customer_id": "cus_123",
    "plan_id": "plan_basic_monthly",
    "trial_period_days": 14,
    "payment_method": "pm_card_123",
    "metadata": {
      "promo_code": "WELCOME20"
    }
  }'

Multi-Item Subscription​

curl https://api.azotte.com/v1/subscriptions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "customer_id": "cus_123",
    "items": [
      {
        "plan_id": "plan_basic",
        "quantity": 1
      },
      {
        "plan_id": "addon_analytics",
        "quantity": 1
      }
    ],
    "discount_coupon": "SAVE10"
  }'

Update Subscription​

# Change plan
curl https://api.azotte.com/v1/subscriptions/sub_123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "plan_id": "plan_premium",
    "proration_behavior": "create_prorations"
  }'

# Pause subscription
curl https://api.azotte.com/v1/subscriptions/sub_123/pause \
  -H "Authorization: Bearer sk_live_..." \
  -X POST

# Resume subscription
curl https://api.azotte.com/v1/subscriptions/sub_123/resume \
  -H "Authorization: Bearer sk_live_..." \
  -X POST

Cancel Subscription​

curl https://api.azotte.com/v1/subscriptions/sub_123/cancel \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "at_period_end": true,
    "cancellation_reason": "customer_request"
  }'

Payment Processing​

Create Payment Method​

curl https://api.azotte.com/v1/payment_methods \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "customer_id": "cus_123",
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2025,
      "cvc": "123"
    }
  }'

Process One-time Payment​

curl https://api.azotte.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 2999,
    "currency": "usd",
    "customer_id": "cus_123",
    "payment_method": "pm_123",
    "description": "One-time setup fee",
    "confirm": true
  }'

Create Refund​

# Full refund
curl https://api.azotte.com/v1/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "payment_id": "pay_123",
    "reason": "requested_by_customer"
  }'

# Partial refund
curl https://api.azotte.com/v1/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "payment_id": "pay_123",
    "amount": 1500,
    "reason": "defective_product"
  }'

Plans and Pricing​

Create Plan​

curl https://api.azotte.com/v1/plans \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "name": "Basic Monthly",
    "id": "basic_monthly",
    "amount": 999,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 14
  }'

List Plans​

curl "https://api.azotte.com/v1/plans?active=true&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Update Plan​

curl https://api.azotte.com/v1/plans/basic_monthly \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "name": "Basic Plan - Updated",
    "metadata": {
      "updated_at": "2024-01-15"
    }
  }'

Invoicing​

Create Invoice​

curl https://api.azotte.com/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "customer_id": "cus_123",
    "auto_advance": true,
    "collection_method": "charge_automatically"
  }'

Add Invoice Item​

curl https://api.azotte.com/v1/invoice_items \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "customer_id": "cus_123",
    "amount": 2500,
    "currency": "usd",
    "description": "Professional services"
  }'

Finalize Invoice​

curl https://api.azotte.com/v1/invoices/in_123/finalize \
  -H "Authorization: Bearer sk_live_..." \
  -X POST

Send Invoice​

curl https://api.azotte.com/v1/invoices/in_123/send \
  -H "Authorization: Bearer sk_live_..." \
  -X POST

Webhooks​

List Webhook Endpoints​

curl https://api.azotte.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..."

Create Webhook Endpoint​

curl https://api.azotte.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "url": "https://myapp.com/webhooks/azotte",
    "enabled_events": [
      "subscription.created",
      "subscription.updated", 
      "payment.succeeded",
      "payment.failed"
    ]
  }'

Update Webhook Endpoint​

curl https://api.azotte.com/v1/webhook_endpoints/we_123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "enabled_events": ["*"],
    "disabled": false
  }'

Metered Billing​

Create Usage Record​

curl https://api.azotte.com/v1/subscription_items/si_123/usage_records \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "quantity": 100,
    "timestamp": 1640995200,
    "action": "increment"
  }'

List Usage Records​

curl "https://api.azotte.com/v1/subscription_items/si_123/usage_records?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer sk_live_..."

Coupons and Discounts​

Create Coupon​

curl https://api.azotte.com/v1/coupons \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "id": "SAVE20",
    "percent_off": 20,
    "duration": "once",
    "max_redemptions": 100,
    "redeem_by": 1672531199
  }'

Apply Coupon to Customer​

curl https://api.azotte.com/v1/customers/cus_123/discount \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "coupon": "SAVE20"
  }'

Disputes​

List Disputes​

curl "https://api.azotte.com/v1/disputes?status=needs_response" \
  -H "Authorization: Bearer sk_live_..."

Update Dispute Evidence​

curl https://api.azotte.com/v1/disputes/dp_123/evidence \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "customer_communication": "Email thread with customer",
    "receipt": "Payment receipt #12345",
    "shipping_documentation": "Tracking number: 1Z999AA1..."
  }'

File Uploads​

Upload File​

curl https://api.azotte.com/v1/files \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@/path/to/document.pdf" \
  -F "purpose=dispute_evidence"

Advanced Queries​

Complex Filtering​

# Multiple filters with AND logic
curl "https://api.azotte.com/v1/customers?created[gte]=2024-01-01&created[lte]=2024-01-31&email[contains]=@company.com&metadata[source]=website" \
  -H "Authorization: Bearer sk_live_..."

# Sorting
curl "https://api.azotte.com/v1/subscriptions?sort=created_at&order=desc&limit=50" \
  -H "Authorization: Bearer sk_live_..."

Searching​

# Search customers by name or email
curl "https://api.azotte.com/v1/customers/search?query=john&limit=10" \
  -H "Authorization: Bearer sk_live_..."

Batch Operations​

Bulk Customer Creation​

curl https://api.azotte.com/v1/customers/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "customers": [
      {
        "name": "Customer 1",
        "email": "customer1@example.com"
      },
      {
        "name": "Customer 2", 
        "email": "customer2@example.com"
      }
    ]
  }'

Error Handling​

Handling Rate Limits​

# Check rate limit headers in response
curl -i https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..."

# Response headers include:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1640995200

Retry with Exponential Backoff​

#!/bin/bash

retry_with_backoff() {
  local max_attempts=5
  local timeout=1
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    if curl -s -f "$@"; then
      return 0
    fi

    echo "Attempt $attempt failed. Retrying in $timeout seconds..."
    sleep $timeout
    timeout=$((timeout * 2))
    attempt=$((attempt + 1))
  done

  echo "All $max_attempts attempts failed."
  return 1
}

# Usage
retry_with_backoff https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..."

Testing with Test Data​

Test Card Numbers​

# Test successful payment
curl https://api.azotte.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "payment_method_data": {
      "type": "card",
      "card": {
        "number": "4242424242424242",
        "exp_month": 12,
        "exp_year": 2025,
        "cvc": "123"
      }
    }
  }'

# Test declined payment
curl https://api.azotte.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 2000,
    "currency": "usd", 
    "payment_method_data": {
      "type": "card",
      "card": {
        "number": "4000000000000002",
        "exp_month": 12,
        "exp_year": 2025,
        "cvc": "123"
      }
    }
  }'

Debugging and Logging​

Verbose Output​

# Show request and response headers
curl -v https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..."

# Save response to file
curl https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -o customers_response.json

# Show timing information
curl -w "@curl-format.txt" https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer sk_live_..."

# curl-format.txt:
#      time_namelookup:  %{time_namelookup}\n
#         time_connect:  %{time_connect}\n
#      time_appconnect:  %{time_appconnect}\n
#     time_pretransfer:  %{time_pretransfer}\n
#        time_redirect:  %{time_redirect}\n
#   time_starttransfer:  %{time_starttransfer}\n
#                      ----------\n
#           time_total:  %{time_total}\n

Environment Variables​

Using Environment Variables for Secrets​

# Set environment variable
export AZOTTE_API_KEY="sk_live_..."
export AZOTTE_TENANT_ID="tenant_123"

# Use in cURL commands
curl https://api.azotte.com/v1/customers \
  -H "Authorization: Bearer $AZOTTE_API_KEY" \
  -H "X-Tenant-ID: $AZOTTE_TENANT_ID"

Configuration File​

# .curlrc file for default options
header = "User-Agent: MyApp/1.0"
connect-timeout = 30
max-time = 60
retry = 3
retry-delay = 2

Next Steps​