Add JsonImport resource for bulk data import (PIP-310)

[wscourge]

Summary

• New JsonImport resource class with dedicated schema for bulk import API responses
• JsonImport.create(config, uuid='ds_...', data={...}): POST /data_sources/{uuid}/json_imports
• JsonImport.retrieve(config, uuid='ds_...', import_id='...'): GET /data_sources/{uuid}/json_imports/{import_id}

Usage

import chartmogul

config = chartmogul.Config("token")

# Import data in bulk
result = chartmogul.JsonImport.create(
    config, uuid='ds_45d064ca-fcf8-11f0-903f-33618f80d753',
    data={
        'external_id': 'import_batch_001',
        'customers': [
            {
                'external_id': 'cus_acme_001',
                'name': 'Acme Corp',
                'email': 'billing@acme.com',
                'company': 'Acme Corporation',
                'country': 'US',
                'state': 'US-CA',
                'city': 'San Francisco',
                'zip': '94105',
                'lead_created_at': '2025-10-15T00:00:00Z',
                'free_trial_started_at': '2025-11-01T00:00:00Z',
            }
        ],
        'plans': [
            {
                'name': 'Professional Monthly',
                'external_id': 'plan_pro_monthly',
                'interval_count': 1,
                'interval_unit': 'month',
            }
        ],
        'invoices': [
            {
                'external_id': 'inv_2025_11_001',
                'customer_external_id': 'cus_acme_001',
                'date': '2025-11-01T00:00:00Z',
                'due_date': '2025-12-01T00:00:00Z',
                'currency': 'USD',
            }
        ],
        'line_items': [
            {
                'invoice_external_id': 'inv_2025_11_001',
                'type': 'subscription',
                'amount_in_cents': 9900,
                'quantity': 5,
                'plan_external_id': 'plan_pro_monthly',
                'subscription_external_id': 'sub_acme_pro',
                'service_period_start': '2025-11-01T00:00:00Z',
                'service_period_end': '2025-12-01T00:00:00Z',
            }
        ],
        'transactions': [
            {
                'invoice_external_id': 'inv_2025_11_001',
                'external_id': 'txn_001',
                'type': 'payment',
                'result': 'successful',
                'date': '2025-11-01T12:30:00Z',
            }
        ],
        'subscription_events': [
            {
                'external_id': 'evt_acme_start',
                'customer_external_id': 'cus_acme_001',
                'subscription_external_id': 'sub_acme_pro',
                'plan_external_id': 'plan_pro_monthly',
                'event_type': 'subscription_start',
                'event_date': '2025-11-01T00:00:00Z',
                'effective_date': '2025-11-01T00:00:00Z',
                'currency': 'USD',
                'amount_in_cents': 9900,
                'quantity': 5,
            }
        ],
    }
).get()
result.id      # "4815d987-..." (use for status tracking)
result.status  # "queued"

# Track import status
status = chartmogul.JsonImport.retrieve(
    config, uuid='ds_45d064ca-fcf8-11f0-903f-33618f80d753',
    import_id=result.id
).get()
status.status          # "completed"
status.status_details  # per-customer breakdown

Backwards compatibility

Change	Breaking?
Added JsonImport resource class	No — new class
Added JsonImport.create method	No — new method
Added JsonImport.retrieve method	No — new method

Test plan

• Added tests for JsonImport.create with realistic bulk import payload (customers, plans, invoices, line items, transactions, subscription events)
• Added tests for JsonImport.retrieve with status response assertions
• Tests assert on all response fields (id, status, external_id, data_source_uuid, status_details)
• All existing tests pass (140 total)

🤖 Generated with Claude Code

[loomchild]

[minor] IMO param should be called data_source_uuid. import_id should be passed as id or perhaps even uuid (but then inconsistent with field name, not sure what we do in other resources in such case; it also doesn't have a prefix, not sure if it's because it's not an independent object.).

[wscourge]

For me it is obvious that if uuid path param is under /data_sources/{uuid} then it is the DataSource's UUID, but being explicit won't hurt, I updated it to data_source_uuid 👍 .

I like the import_id to id update, I don't want to use uuid because the id is what Import Data in Bulk responds with:

[loomchild]

Makes sense, thanks.

[loomchild]

LGTM and works for me, thanks for the changes.