Import Invoices

POST https://api.chartmogul.com/v1/import/customers/{CUSTOMER_UUID}/invoices

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

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": "inv_0001",
                "date": "2022-11-10 `00:00:00`",
                "currency": "USD",
                "due_date": "2022-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": "2022-11-10 `00:00:00`",
                    "service_period_end": "2022-12-01 `00:00:00`",
                    "amount_in_cents": 5000,
                    "prorated":true,
                    "proration_type": "differential",
                    "quantity": 1,
                    "discount_code": "PSO86",
                    "discount_amount_in_cents": 1000,
                    "tax_amount_in_cents": 900,
                    "transaction_fees_in_cents": 200,
                    "transaction_fees_currency": "USD",
                    "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": "USD",
                    "discount_description": "New signup promo"
                  }
                ],
                "transactions": [
                  {
                    "date": "2022-11-10 00:14:23",
                    "type": "payment",
                    "result": "successful"
                  }
                ]   
              }
            ]
        }'

line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  subscription_set_external_id: "set_0001",
  plan_uuid: "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  service_period_start: Time.utc(2022, 11, 10),
  service_period_end: Time.utc(2022, 12, 1),
  amount_in_cents: 5000,
  prorated: true,
  proration_type: "differential",
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 1000,
  tax_amount_in_cents: 900,
  transaction_fees_in_cents: 200,
  transaction_fees_currency: "USD",
  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: "USD",
  discount_description: "New signup promo",
)

transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2022, 11, 10, 0, 14, 23),
  result: "successful",
)

invoice = ChartMogul::Invoice.new(
  external_id: "inv_0001",
  date: Time.utc(2022, 11, 10),
  currency: "USD",
  due_date: Time.utc(2022, 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: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  invoices: [invoice],
)

const invoices = {
  invoices: [
    {
      external_id: "inv_0001",
      date: "2022-11-10 `00:00:00`",
      currency: "USD",
      due_date: "2022-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: "2022-11-10 `00:00:00`",
          service_period_end: "2022-12-01 `00:00:00`",
          amount_in_cents: 5000,
          prorated: true,
          proration_type: "differential",
          quantity: 1,
          discount_code: "PSO86",
          discount_amount_in_cents: 1000,
          tax_amount_in_cents: 900,
          transaction_fees_currency: "USD",
          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: "USD",
          discount_description: "New signup promo",
        },
      ],
      transactions: [
        {
          date: "2022-11-10 00:14:23",
          type: "payment",
          result: "successful",
        },
      ],
    },
  ],
};

ChartMogul.Invoice.create(
  config,
  "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  invoices
);

$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" => "2022-11-`10T00:00:00`.000Z",
  "service_period_end" => "2022-12-`01T00:00:00`Z",
  "amount_in_cents" => 5000,
  "prorated" => true,
  "proration_type" => "differential",
  "quantity" => 1,
  "discount_code" => "PSO86",
  "discount_amount_in_cents" => 1000,
  "tax_amount_in_cents" => 900,
  "transaction_fees_currency" => "USD",
  "discount_description" => "New signup promo",
  "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" => "USD",
  "discount_description" => "New signup promo"
]);

$transaction = new ChartMogul\Transactions\Payment([
  "date" => "2022-11-10 00:14:23",
  "result" => "successful"
]);

$invoice = new ChartMogul\Invoice([
  "external_id" => "inv_0001",
  "date" => "2022-11-10 `00:00:00`",
  "due_date" => "2022-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]
]);

ChartMogul\CustomerInvoices::create([
  "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "invoices" => [$invoice]
]);

api.CreateInvoices([]*cm.Invoice{
  &cm.Invoice{
    ExternalID:         "inv_0001",
    Date:               "2022-11-10 `00:00:00`",
    Currency:           "USD",
    DueDate:            "2022-11-15 `00:00:00`",
    CustomerExternalID: "cus_0001",
    DataSourceUUID:     "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    LineItems: []*cm.LineItem{
      &cm.LineItem{
        Type:                      "subscription",
        SubscriptionExternalID:    "sub_0001",
        SubscriptionSetExternalID: "set_0001",
        PlanUUID:                  "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
        ServicePeriodStart:        "2022-11-10 `00:00:00`",
        ServicePeriodEnd:          "2022-12-01 `00:00:00`",
        AmountInCents:             5000,
        Prorated:                  true,
        Quantity:                  1,
        DiscountCode:              "PSO86",
        DiscountAmountInCents:     1000,
        TaxAmountInCents:          900,
        TransactionFeesInCents:    200,
        TransactionFeesCurrency:   "USD",
        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: "USD",
        DiscountDescription:     "New signup promo",
      }},
    Transactions: []*cm.Transaction{
      &cm.Transaction{
        Date:   "2022-11-10 00:14:23",
        Type:   "payment",
        Result: "successful",
      }},
  }}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
)

chartmogul.Invoice.create(
  config,
  uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  data={
    "invoices": [
      {
        "external_id": "inv_0001",
        "date": "2022-11-10 `00:00:00`",
        "currency": "USD",
        "due_date": "2022-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": "2022-11-10 `00:00:00`",
            "service_period_end": "2022-12-01 `00:00:00`",
            "amount_in_cents": 5000,
            "prorated": True,
            "proration_type": "differential",
            "quantity": 1,
            "discount_code": "PSO86",
            "discount_amount_in_cents": 1000,
            "tax_amount_in_cents": 900,
            "transaction_fees_in_cents": 200,
            "transaction_fees_currency": "USD",
            "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": "USD",
            "discount_description": "New signup promo",
          },
        ],
        "transactions": [
          {
            "date": "2022-11-10 00:14:23",
            "type": "payment",
            "result": "successful",
          }
        ],
      }
    ]
  },
)

{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "inv_0001",
      "date": "2022-11-`10T00:00:00`.000Z",
      "due_date": "2022-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": true,
          "proration_type": "differential",
          "service_period_start": "2022-11-`10T00:00:00`.000Z",
          "service_period_end": "2022-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": "USD",
          "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": "USD",
          "discount_description": "New signup promo",
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2022-11-10T00: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="inv_0001", 
      @date=2022-11-10 `00:00:00` UTC,
      @due_date=2022-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=2022-11-10 `00:00:00` UTC,
          @service_period_end=2022-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=true,
          @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
          @transaction_fees_currency="USD",
          @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="USD",
          @discount_description="New signup promo",
          @account_code=nil
        >
      ], 
      @transactions=[
        #<ChartMogul::Transactions::Payment:0x007fb4991013f0 
          @uuid="tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          @external_id=nil,
          @date=2022-11-10 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: "inv_0001",
      date: "2022-11-`10T00:00:00`.000Z",
      due_date: "2022-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: true,
          proration_type: "differential",
          service_period_start: "2022-11-`10T00:00:00`.000Z",
          service_period_end: "2022-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: "USD",
          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: "USD",
          discount_description: "New signup promo",
          account_code: null
        }
      ],
      transactions: [
        {
          uuid: "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          external_id: null,
          type: "payment",
          date: "2022-11-10T00:14:23.000Z",
          result: "successful"
        }
      ]
    }
  ]
}

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" => "2022-11-`10T00:00:00`.000Z",
        "external_id" => "inv_0001",
        "due_date" => "2022-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" => "2022-11-`10T00:00:00`.000Z",
              "service_period_end" => "2022-12-`01T00:00:00`.000Z",
              "cancelled_at" => NULL,
              "prorated" => true,
              "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" => 1,
              "discount_amount_in_cents" => 1000,
              "discount_code" => "PSO86",
              "tax_amount_in_cents" => 900,
              "transaction_fees_in_cents" => 0,
              "external_id" => NULL,
              "invoice_uuid" => NULL,
              "transaction_fees_currency" => "USD",
              "discount_description" => "New signup promo",
              "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" => "USD",
              "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" => "2022-11-10T00: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_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    Currency: (string) (len=3) "USD",
    Date: (string) (len=24) "2022-11-`10T00:00:00`.000Z",
    DueDate: (string) (len=24) "2022-11-`15T00:00:00`.000Z",
    ExternalID: (string) (len=7) "inv_0001",
    LineItems: ([]*chartmogul.LineItem) (len=2) {
      (*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_eed05d54-75b4-431b-adb2-eb6b9e543206",
      Prorated: (bool) true,
      Quantity: (int) 1,
      ServicePeriodEnd: (string) (len=24) "2022-12-`01T00:00:00`.000Z",
      ServicePeriodStart: (string) (len=24) "2022-11-`10T00: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) "USD",
      DiscountDescription: (string) "New signup promo",
      EventOrder: (int) 5,
      Type: (string) (len=12) "subscription"
      }),
      (*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) "USD",
      DiscountDescription: (string) "New signup promo",
      Type: (string) (len=8) "one_time"
      })
    },
    Transactions: ([]*chartmogul.Transaction) (len=1) {
      (*chartmogul.Transaction)(0xc0420e2c00)(Transaction() successful payment (2022-11-10T00:14:23.000Z))
    },
    Errors: (*chartmogul.Errors)(<nil>)
    })
  }
})

Invoices(
  invoices=[
    <Invoice{
      currency="USD",
      date=datetime.datetime(2022, 11, 10, 0, 0),
      due_date=datetime.datetime(2022, 11, 15, 0, 0),
      external_id="inv_0001",
      line_items=[
        <LineItem{
          account_code="",
          amount_in_cents=5000,
          discount_amount_in_cents=1000,
          discount_code="PSO86",
          external_id=None,
          plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          prorated=True,
          quantity=1,
          service_period_end=datetime.datetime(2022, 12, 1, 0, 0),
          service_period_start=datetime.datetime(2022, 11, 10, 0, 0),
          subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          subscription_external_id="sub_0001",
          subscription_set_external_id="set_0001",
          tax_amount_in_cents=900,
          transaction_fees_in_cents=200,
          transaction_fees_currency="USD",
          discount_description="New signup promo",
          event_order=5,
          type="subscription",
          uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56"
        }>,
        <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="USD",
          discount_description="New signup promo",
          type="one_time",
          uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83"
        }>,
      ]
      transactions=[
        <Transaction{
          date=datetime.datetime(2022, 11, 10, 0, 14, 23),
          external_id=None,
          result="successful",
          type="payment",
          uuid="tr_879d560a-1bec-41bb-986e-665e38a2f7bc"
        }>
      ],
      uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9"
    }>
  ],
  current_page=None,
  total_pages=None
)

Path parameters

customer_uuid string required: The ChartMogul UUID of the Customer that these invoices belong to.

Body parameters

external_id string required: A unique identifier specified by you for the invoice. Typically the Invoice Number in your system. Accepts alphanumeric characters.
date string required: The date and time on which this invoice was raised. Must be an ISO 8601 formatted date and time. The timezone defaults to UTC if not specified. The time defaults to 00:00:00 if not specified.
currency string required: The 3-letter currency code of the currency in which this invoice is being billed, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies.
line_items array(object) required: A list of Line Item objects. See table below for Line Item attributes.
customer_external_id string required: A unique identifier specified by you for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters. This parameter is normally optional but required when importing invoices for merged customers in ChartMogul.
data_source_uuid string: The ChartMogul UUID of the Data Source to which these invoices should be attributed. This parameter is normally optional but required when importing invoices for merged customers in ChartMogul.
transactions array(object): A list of Transaction objects. See table below for Transaction attributes.
due_date string: The date within which this invoice must be paid. 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.

Line Item Attributes

These parameters apply to both one-time line items as well as subscription line items.

type string required

Either subscription or one_time. See the subscription line items section and the one-time line items section for more details about parameters specific to the set type.

amount_in_cents integer required

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.

quantity integer default: 1

The quantity/seats of the subscription being billed by this line item. Can be any non-zero integer. Defaults to 1.

Quantity value does not impact calculation of MRR. It is used for additional segmentation by subscription quantity and generating Subscription Quantity charts.

discount_amount_in_cents integer default: 0

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 string

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

tax_amount_in_cents integer default: 0

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 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 string

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

account_code 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 string

The 3-letter currency code for transaction_fees_in_cents, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies.

discount_description string

A short description of discount_amount_in_cents.

event_order integer

Used for ordering events that happen at the same time.

Subscription line items

The parameters below apply to line item objects that have the type set to subscription.

subscription_external_id string required

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

subscription_set_external_id string

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

plan_uuid string required

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

service_period_start timestamp required

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 timestamp required

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.

cancelled_at 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 boolean

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

proration_type string

If not provided, or set to differential, prorated line items are classified as an upgrade or downgrade and added to previously calculated MRR and subscription quantity.

If set to full, prorated line items have a partial service period, and do not take previously calculated MRR and subscription quantity into consideration.

If set to differential_mrr, the amount from this prorated line item behaves like differential proration, which means it is added to previously calculated MRR. The quantity from this prorated line item behaves like full proration, which means it is not added to previously calculated subscription quantity.

One-time line items

The parameters below apply to line item objects that have the type set to one_time.

plan_uuid string: The ChartMogul UUID of the plan for which this subscription is being charged.
description string: A short description of the non-recurring item being charged to the customer.

Transaction Attributes

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

date timestamp required

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 string required

Either one of payment or refund.

result string required

Either one of successful or failed.

amount_in_cents 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 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.
Import invoices into a custom source. Data imported into other sources (e.g., Stripe) may be lost during a re-sync.
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 the ChartMogul interface 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.