Import Invoices

Creates invoices for a given API customer. ChartMogul auto-generates subscription objects from these invoices.

Examples
curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0001",
          "date": "2015-11-01 00:00:00",
          "currency": "USD",
          "due_date": "2015-11-15 00:00:00",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "subscription_set_external_id": "set_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2015-11-01 00:00:00",
              "service_period_end": "2015-12-01 00:00:00",
              "amount_in_cents": 5000,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 1000,
              "tax_amount_in_cents": 900,
              "transaction_fees_in_cents": 200,
              "transaction_fees_currency": "EUR",
              "discount_description": "New signup promo",
              "event_order": 5
            },
            {
              "type": "one_time",
              "description": "Setup Fees",
              "amount_in_cents": 2500,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 500,
              "tax_amount_in_cents": 450,
              "transaction_fees_currency": "EUR",
              "discount_description": "New signup promo"
            }
          ],
          "transactions": [
            {
              "date": "2015-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0001").first

line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  subscription_set_external_id: "set_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2015, 11, 1),
  service_period_end: Time.utc(2015, 12, 1),
  amount_in_cents: 5000,
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 1000,
  tax_amount_in_cents: 900,
  transaction_fees_in_cents: 200,
  transaction_fees_currency: "EUR",
  discount_description: "New signup promo",
  event_order: 5
)
line_item_2 = ChartMogul::LineItems::OneTime.new(
  description: "Setup Fees",
  amount_in_cents: 2500,
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 500,
  tax_amount_in_cents: 450,
  transaction_fees_currency: "EUR",
  discount_description: "New signup promo"
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 11, 5, 0, 14, 23),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
    external_id: 'INV0001',
  date: Time.utc(2015, 11, 1),
  currency: 'USD',
  due_date: Time.utc(2015, 11, 15),
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  line_items: [line_item_1, line_item_2],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])
const invoices = {
    invoices: [{
        external_id: 'INV0001',
        date: '2015-11-01 00:00:00',
        currency: 'USD',
        due_date: '2015-11-15 00:00:00',
        line_items: [
            {
                type: 'subscription',
                subscription_external_id: 'sub_0001',
                plan_uuid: 'pl_eed05d54-75b4-431b-adb2-eb6b9e543206',
                service_period_start: '2015-11-01 00:00:00',
                service_period_end: '2015-12-01 00:00:00',
                amount_in_cents: 5000,
                quantity: 1,
                discount_code: 'PSO86',
                discount_amount_in_cents: 1000,
                tax_amount_in_cents: 900,
                transaction_fees_currency: 'EUR',
                discount_description: 'New signup promo',
                event_order: 5
            },
            {
                type: 'one_time',
                description: 'Setup Fees',
                amount_in_cents: 2500,
                quantity: 1,
                discount_code: 'PSO86',
                discount_amount_in_cents: 500,
                tax_amount_in_cents: 450,
                transaction_fees_currency: 'EUR',
                discount_description: 'New signup promo'
            }
        ],
        transactions: [
            {
                date: '2015-11-05 00:14:23',
                type: 'payment',
                result: 'successful'
            }
        ]
    }]
};

ChartMogul.Invoice.create(config, 'cus_f466e33d-ff2b-4a11-8f85-417eb02157a7', invoices)
<?php

$line_item1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "subscription_set_external_id" => "set_0001",
    "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
    "service_period_start" => "2015-07-01T00:00:00.000Z",
    "service_period_end" => "2016-01-01T00:00:00Z",
    "amount_in_cents" => -5000,
    "quantity" => -10,
    "transaction_fees_currency" => "EUR",
    "event_order" => 5
]);
$line_item2 = new ChartMogul\LineItems\OneTime([
    "description" => "Setup Fees",
    "amount_in_cents" => 2500,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 500,
    "tax_amount_in_cents" => 450,
    "transaction_fees_currency" => "EUR",
    "discount_description" => "New signup promo"
]);
$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2015-11-05 00:14:23",
    "result" => "successful"
]);
$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0001",
    "date" => "2015-11-01 00:00:00",
    "due_date" => "2015-11-15 00:00:00",
    "currency" => "USD",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "line_items" => [$line_item1, $line_item2],
    "transactions" => [$transaction]
]);
$ci = ChartMogul\CustomerInvoices::create([
            "customer_uuid" => $cu->uuid,
            "invoices" => [$invoice]
]);
?>
api.CreateInvoices([]*cm.Invoice{
  &cm.Invoice{
        ExternalID: "INV0002",
        Date:       "2015-11-01 00:00:00",
        Currency:   "USD",
        DueDate:    "2015-11-15 00:00:00",
    CustomerExternalID: "cus_0001",
    DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
        LineItems: []*cm.LineItem{
            &cm.LineItem{
                Type:                                 "subscription",
        SubscriptionExternalID:       "sub_0002",
        SubscriptionSetExternalID:  "set_0002",
        PlanUUID:                       "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
                ServicePeriodStart:             "2015-11-01 00:00:00",
                ServicePeriodEnd:               "2015-12-01 00:00:00",
                AmountInCents:                  5000,
                Quantity:                       1,
                DiscountCode:                   "PSO86",
                DiscountAmountInCents:          1000,
                TaxAmountInCents:               900,
        TransactionFeesInCents:         200,
        TransactionFeesCurrency:    "EUR",
        DiscountDescription:            "New signup promo",
        EventOrder:                                 5
            },
            &cm.LineItem{
                Type:                    "one_time",
                Description:             "Setup Fees",
                AmountInCents:           2500,
                Quantity:                1,
                DiscountCode:            "PSO86",
                DiscountAmountInCents:   500,
                TaxAmountInCents:        450,
        TransactionFeesInCents:  0,
        TransactionFeesCurrency: "EUR",
        DiscountDescription:         "New signup promo"
            }},
        Transactions: []*cm.Transaction{
            &cm.Transaction{
                Date:   "2015-11-05 00:14:23",
                Type:   "payment",
                Result: "successful",
            }},
    }}, "cus_c0dc8d74-edfd-11e6-a357-832dddba822f")
import chartmogul

chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [
         {
             "external_id": "INV0001",
             "date": "2015-11-01 00:00:00",
             "currency": "USD",
             "due_date": "2015-11-15 00:00:00",
             "customer_external_id": "cus_0001",
             "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
             "line_items": [
                 {
                     "type": "subscription",
                     "subscription_external_id": "sub_0001",
                     "subscription_set_external_id": "set_0001",
                     "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                     "service_period_start": "2015-11-01 00:00:00",
                     "service_period_end": "2015-12-01 00:00:00",
                     "amount_in_cents": 5000,
                     "quantity": 1,
                     "discount_code": "PSO86",
                     "discount_amount_in_cents": 1000,
                     "tax_amount_in_cents": 900,
                     "transaction_fees_in_cents": 200,
                     "transaction_fees_currency": "EUR",
                     "discount_description": "New signup promo",
                     "event_order": 5
                 },
                 {
                     "type": "one_time",
                     "description": "Setup Fees",
                     "amount_in_cents": 2500,
                     "quantity": 1,
                     "discount_code": "PSO86",
                     "discount_amount_in_cents": 500,
                     "tax_amount_in_cents": 450,
                     "transaction_fees_currency": "EUR",
                     "discount_description": "New signup promo"
                 }
             ],
             "transactions": [
                 {
                     "date": "2015-11-05 00:14:23",
                     "type": "payment",
                     "result": "successful"
                 }
             ]
         }
        ]
    })
Result Format
{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "subscription_set_external_id": "set_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "transaction_fees_in_cents": 200,
          "transaction_fees_currency": "EUR",
          "discount_description": "New signup promo",
          "event_order": 5,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "transaction_fees_in_cents": 0,
          "transaction_fees_currency": "EUR",
          "discount_description": "New signup promo",
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ]
}
#<ChartMogul::CustomerInvoices:0x007fb49884b850 
@customer_uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
@invoices=[
  #<ChartMogul::Invoice:0x007fb498a04660 
  @uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
  @external_id="INV0001", 
  @date=2015-11-01 00:00:00 UTC,
  @due_date=2015-11-15 00:00:00 UTC, 
  @currency="USD", 
  @line_items=[
    #<ChartMogul::LineItems::Subscription:0x007fb4994d23f8 
    @uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56",
    @external_id=nil, 
    @type="subscription",
    @subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
    @subscription_external_id="sub_0001", 
    @subscription_set_external_id="set_0001", 
    @plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206", 
    @service_period_start=2015-11-01 00:00:00 UTC, 
    @service_period_end=2015-12-01 00:00:00 UTC, 
    @amount_in_cents=5000, 
    @quantity=1, 
    @discount_code="PSO86",
    @discount_amount_in_cents=1000,
    @tax_amount_in_cents=900,
    @transaction_fees_in_cents=200,
    @cancelled_at=nil,
    @prorated=false,
    @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    @transaction_fees_currency="EUR",
    @discount_description="New signup promo",
    @event_order=5,
    @account_code=nil
    >,
    #<ChartMogul::LineItems::OneTime:0x007fb499149358 
    @uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83",
    @external_id=nil,
    @type="one_time",
    @amount_in_cents=5000, 
    @description="Setup Fees", 
    @quantity=1, 
    @discount_amount_in_cents=1000, 
    @discount_code="PSO86", 
    @tax_amount_in_cents=900,
    @transaction_fees_in_cents=0,
    @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    @transaction_fees_currency="EUR",
    @discount_description="New signup promo",
    @account_code=nil
    >
  ], 
  @transactions=[
    #<ChartMogul::Transactions::Payment:0x007fb4991013f0 
    @uuid="tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
    @external_id=nil,
    @date=2015-11-05 00:14:23 UTC, 
    @result="successful", 
    @type="payment",
    @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9"
    >
  ]
  >
]
>
{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "subscription_set_external_id": "set_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "transaction_fees_in_cents": 200,
          "transaction_fees_currency": "EUR",
          "discount_description": "New signup promo",
          "event_order": 5,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "transaction_fees_in_cents": 0,
          "transaction_fees_currency": "EUR",
          "discount_description": "New signup promo",
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ]
}
<?php

ChartMogul\CustomerInvoices::__set_state(array(
   "invoices" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Invoice::__set_state(array(
         "uuid" => "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
         "date" => "2015-11-01T00:00:00.000Z",
         "external_id" => "INV0001",
         "due_date" => "2015-11-15T00:00:00.000Z",
         "currency" => "USD",
         "line_items" => 
        Doctrine\Common\Collections\ArrayCollection::__set_state(array(
           "elements" => 
          array (
            0 => 
            ChartMogul\LineItems\Subscription::__set_state(array(
               "type" => "subscription",
               "subscription_external_id" => "sub_0001",
               "subscription_set_external_id" => "set_0001",
               "service_period_start" => "2015-07-01T00:00:00.000Z",
               "service_period_end" => "2016-01-01T00:00:00.000Z",
               "cancelled_at" => NULL,
               "prorated" => false,
               "subscription_uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
               "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
               "uuid" => "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
               "amount_in_cents" => -5000,
               "quantity" => -10,
               "discount_amount_in_cents" => 0,
               "discount_code" => "",
               "tax_amount_in_cents" => 0,
               "transaction_fees_in_cents" => 0,
               "external_id" => NULL,
               "invoice_uuid" => NULL,
               "transaction_fees_currency" => "EUR",
               "event_order" => 5,
               "account_code" => ""
            )),
            1 => 
            ChartMogul\LineItems\OneTime::__set_state(array(
               "type" => "one_time",
               "description" => "Setup Fees",
               "uuid" => "li_0cc8c112-beac-416d-af11-f35744ca4e83",
               "amount_in_cents" => 2500,
               "quantity" => 1,
               "discount_amount_in_cents" => 500,
               "discount_code" => "PSO86",
               "tax_amount_in_cents" => 450,
               "transaction_fees_in_cents" => 0,
               "external_id" => NULL,
               "invoice_uuid" => NULL,
               "transaction_fees_currency" => "EUR",
               "discount_description" => "New signup promo",
               "account_code" => ""
            )),
          ),
        )),
         "transactions" => 
        Doctrine\Common\Collections\ArrayCollection::__set_state(array(
           "elements" => 
          array (
            0 => 
            ChartMogul\Transactions\Payment::__set_state(array(
               "type" => "payment",
               "uuid" => "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
               "date" => "2015-11-05T00:14:23.000Z",
               "result" => "successful"
           )))
        ))
)))))));
?>
(*chartmogul.Invoices)(0xc0420085c0)({
 CustomerUUID: (string) "",
 CurrentPage: (uint32) 0,
 TotalPages: (uint32) 0,
 Error: (string) "",
 Invoices: ([]*chartmogul.Invoice) (len=1) {
  (*chartmogul.Invoice)(0xc04210a5a0)({
   UUID: (string) (len=40) "inv_36045157-e5df-45f5-bd96-a8e6bbe08517",
   Currency: (string) (len=3) "USD",
   Date: (string) (len=24) "2015-11-01T00:00:00.000Z",
   DueDate: (string) (len=24) "2015-11-15T00:00:00.000Z",
   ExternalID: (string) (len=7) "INV0002",
   LineItems: ([]*chartmogul.LineItem) (len=2) {
    (*chartmogul.LineItem)(0xc0421cb080)({
     AmountInCents: (int) 2500,
     CancelledAt: (string) "",
     Description: (string) (len=10) "Setup Fees",
     DiscountAmountInCents: (int) 500,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) "",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) "",
     ServicePeriodStart: (string) "",
     SubscriptionExternalID: (string) "",
     SubscriptionUUID: (string) "",
     TaxAmountInCents: (int) 450,
     TransactionFeesInCents: (int) 0,
     TransactionFeesCurrency: (string) "EUR",
     DiscountDescription: (string) "New signup promo",
     Type: (string) (len=8) "one_time"
    }),
    (*chartmogul.LineItem)(0xc0421cb140)({
     AmountInCents: (int) 5000,
     CancelledAt: (string) "",
     Description: (string) "",
     DiscountAmountInCents: (int) 1000,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) (len=24) "2015-12-01T00:00:00.000Z",
     ServicePeriodStart: (string) (len=24) "2015-11-01T00:00:00.000Z",
     SubscriptionExternalID: (string) "sub_0001",
     SubscriptionSetExternalID: (string) (len=8) "set_0001",
     SubscriptionUUID: (string) "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
     TaxAmountInCents: (int) 900,
     TransactionFeesInCents: (int) 200,
     TransactionFeesCurrency: (string) "EUR",
     DiscountDescription: (string) "New signup promo",
     EventOrder: (int) 5,
     Type: (string) (len=12) "subscription"
    })
   },
   Transactions: ([]*chartmogul.Transaction) (len=1) {
    (*chartmogul.Transaction)(0xc0420e2c00)(Transaction() successful payment (2015-11-05T00:14:23.000Z))
   },
   Errors: (*chartmogul.Errors)(<nil>)
  })
 }
})
Invoices(invoices=[<Invoice{
    currency='USD',
    date=datetime.datetime(2015, 11, 1, 0, 0),
    due_date=datetime.datetime(2015, 11, 15, 0, 0),
    external_id='INV0001',
    line_items=[
        <LineItem{
            account_code='',
            amount_in_cents=2500,
            discount_amount_in_cents=500,
            discount_code='PSO86',
            external_id=None,
            quantity=1,
            tax_amount_in_cents=450,
            transaction_fees_in_cents=0,
            transaction_fees_currency='EUR',
            discount_description='New signup promo',
            type='one_time',
            uuid='li_15c316b4-6b41-4673-9c58-6070c3c9b5c9'}>,
        <LineItem{
            account_code='',
            amount_in_cents=5000,
            discount_amount_in_cents=1000,
            discount_code='PSO86',
            external_id=None,
            plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694',
            prorated=False,
            quantity=1,
            service_period_end=datetime.datetime(2015, 12, 1, 0, 0),
            service_period_start=datetime.datetime(2015, 11, 1, 0, 0),
            subscription_uuid='sub_b8ba9b19-0d7d-401c-ad99-496104b435f1',
            subscription_external_id='sub_0001',
            subscription_set_external_id='set_0001',
            tax_amount_in_cents=900,
            transaction_fees_in_cents=200,
            transaction_fees_currency='EUR',
            discount_description='New signup promo',
            event_order=5,
            type='subscription',
            uuid='li_80c5c60c-bbb6-459c-bfba-9e6eaa458d5f'}>],
    transactions=[
        <Transaction{
            date=datetime.datetime(2015, 11, 5, 0, 14, 23),
            external_id=None,
            result='successful',
            type='payment',
            uuid='tr_9f5162d6-d2a7-4d35-bdf9-03be5d901b42'}>],
    uuid='inv_7ca4b8e7-6f90-446c-9fdf-6433e9999f96'}>],
current_page=None,
total_pages=None)

Line Item Attributes

The table below lists the expected parameters for every line_item object that is included in an invoice object.

Attribute

Required?

Datatype

Description

type

Yes

String

One of either subscription or one_time.

subscription_external_id

Yes, for subscription line items.
Irrelevant for one_time line items.

String

A reference identifier for the subscription in your system. Accepts alphanumeric characters.

subscription_set_external_id

No. Only relevant for subscription line items

String

A reference identifier for a set of subscriptions in order to group several subscriptions into one set.

plan_uuid

Yes, for subscription line items.
Optional for one_time line items.

String

The ChartMogul UUID of the plan for which this subscription is being charged.

service_period_start

Yes, for subscription line items.
Irrelevant for one_time line items.

Timestamp

The start of the service period for which this subscription is being charged.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

service_period_end

Yes, for subscription line items.
Irrelevant for one_time line items.

Timestamp

The end of the service period for which this subscription is being charged.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

amount_in_cents

Yes

Integer

The final amount charged towards this line item, for the specified quantity and service period, after discounts, taxes and fees have been applied. Expected in cents (or pence for GBP, etc.)

This is the amount that is primarily used to calculate MRR.

cancelled_at

No. Accepted for subscription line items.
Irrelevant for one_time line items.

Timestamp

If this subscription has been cancelled, the time of cancellation.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless otherwise specified.

prorated

No. Accepted for subscription line items.
Irrelevant for one_time line items.

Boolean

If this is a prorated charge, then set this attribute to true.

description

No. Accepted for one_time line items.
Ignored for subscription line items.

String

A short description of the non-recurring item being charged to the customer.

quantity

No

Integer

The quantity of this line item being billed. Can be any non-zero integer. Defaults to 1.

Quantity value does not impact calculation of MRR.

discount_amount_in_cents

No

Integer

If any discount has been applied to this line item, then the discount amount in cents. Defaults to 0.

Discount amount does not impact calculation of MRR.

discount_code

No

String

If a discount has been applied to this line item, then an optional reference code to identify the discount.

tax_amount_in_cents

No

Integer

The tax that has been applied to this line item, in cents. Defaults to 0.

If specified, we exclude tax amount from MRR.

transaction_fees_in_cents

No

Integer

The final total transaction fees paid to billing provider and/or payment processor for this line item. Expected in cents (or pence for GBP, etc.).

external_id

No

String

A unique identifier specified by you for the line item. Typically an identifier from your internal system. Accepts alphanumeric characters.

account_code

No

String

The unique account code of this line item used for the purposes of accounting and revenue recognition. Also called "account number" in some systems. Accepts a maximum of 30 alphanumeric characters.

transaction_fees_currency

No

String

Currency of transaction_fees_in_cents. Expected EUR, but could be GBP (transaction_fees_in_cents would refer to pence then) etc.

discount_description

No

String

A short description of discount_amount_in_cents.

event_order

No

Integer

Using this for ordering events that happen at the same time.

Transaction Attributes

The table below lists the expected parameters for every transaction object that is included in an invoice object.

Attribute

Required?

Datatype

Description

date

Yes

Timestamp

The timestamp of when the transaction was attempted.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

type

Yes

String

Either one of payment or refund.

result

Yes

String

Either one of successful or failed.

amount_in_cents

No

Integer

The partial amount paid/refunded for this invoice. Expected in cents (or pence for GBP, etc.).

If this field is not mentioned it will default to full amount. The sum of the partial payments/refunds should not exceed the invoiced amount

external_id

No

String

A unique identifier specified by you for the transaction. Typically an identifier from your internal system. Accepts alphanumeric characters.

📘

Invoice total

The invoice total is calculated with the following basic formula:
SUM of (amount_in_cents of each line_item on the invoice)

The transaction amount can be used to denote a partial payment or partial refund. The sum of partial payments and refunds cannot exceed the invoiced amount

📘

MRR Calculation

ChartMogul uses several attributes from invoices to calculate MRR. Below, we describe some of the attributes in the context of their impact on MRR calculations.

  • Amount paid - The amount paid for a subscription is the primary driver in calculating MRR. In the Import API, this is represented by the amount_in_cents attribute.
  • Plans - With monthly plans the MRR is simply the price paid each month for the subscription. If customers are paying for plans with longer billing intervals (e.g. 12 months) ChartMogul simply divides the amount paid for the subscription by the number of months in the subscription period.
  • Discounts - We assume that discounts have already been deducted from the specified amount_in_cents value. For this reason, if discount_amount_in_cents is specified it doesn’t impact MRR but enables more detailed analysis in ChartMogul.
  • Taxes - Taxes must be excluded from the calculation of MRR. If specified, tax_amount_in_cents is used to deduct the tax prior to the calculation of MRR.
  • Quantity - Subscription quantity does not factor in the calculation of MRR. If specified, quantity is used to generate the Subscriptions Quantity and Quantity Churn Rate charts.
  • Prorated - Prorated items in invoices need to be explicitly identified for us to calculate their MRR contribution correctly. If specified as true, the prorated attribute impacts the calculation of MRR. For more details on how proration works, read our tutorial on adding pro-rated invoices.
  • One-time payments are excluded from MRR.

To give an example, let's imagine that:

  • Your customer Adam Smith buys 2 subscriptions to the Gold Monthly Plan.
  • Each Gold Monthly Plan is priced at $100 per month, including a $9 tax.
  • You provide a $20 discount on the total purchase amount.
  • Adam therefore pays $180 for this purchase.

These are the line item attributes for this example:

  • type: subscription
  • plan_uuid: The UUID of the Gold Monthly Plan
  • amount_in_cents: 18000
  • tax_amount_in_cents: 1800
  • discount_amount_in_cents: 2000
  • quantity: 2

In this scenario the MRR will be calculated as: ($180 - $18) = $162 MRR

📘

What you need to know

  • Once a valid request is received by the API, it will respond with 202 - Accepted, and the invoice importing function will proceed to work asynchronously.
  • Your data will be processed and reported faster if you send us batches of customer invoices with each request, instead of one invoice per request.
  • ChartMogul calculates MRR related metrics from invoice line items, and cash flow reports based on transaction information. If you send us an invoice with no transactions then there will be no contribution to cash flow from that invoice.
  • Currently, ChartMogul only allows you to import invoices for customers created using a Custom data source. This means that users cannot import invoices for integrations maintained by ChartMogul - Stripe, Braintree, Recurly, Chargify, or PayPal.
  • Once imported, it is not yet possible to edit invoices or their line items and transactions via the API. If you want to make changes to an invoice, you have to delete it first and import the invoice with updated data or use our data platform UI to update the information.
  • The customer and plan needs to belong to the same datasource otherwise an error will be returned asking for a valid plan UUID
  • The subscription_set_external_id field is optional, and can be included among the invoice line items. Subscriptions that have matching values will be considered to be part of the same set, and as such be represented as separate components of the same subscription on the customer’s page.
  • The customer_external_id and data_source_uuid fields are required only when the customer is a merged customer. When two customers from the same data source are merged then customer_external_id helps to remove ambiguity. And If two customers from different data sources are merged, then specifying data_source_uuid could help to remove ambiguity. If fields customer_external_id and/or data_source_uuid are missing in the invoice object and the customer is merged customer, the request will fail with the response:
    "customer":"Ambiguous customer for specified customer_uuid and `_provided_attribute_`. Specifying _missing_attribute_ will remove ambiguity.
    Missing attribute (_missing_attribute_) and provided attribute (_provided_attribute_) can be both customer_external_id and data_source_uuid or one of the fields.
    In this case, the invoice will not be applied to any customer until both fields customer_external_id and data_source_uuid are provided in the invoice object. It is recommended to include both values to avoid issues in the future.
Language
Authentication
Basic
base64
: