Reference
Help Center

Import Invoices

post https://api.chartmogul.com/v1/import/customers//invoices

Creates invoices for a given API customer. ChartMogul auto-generates subscription objects from 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": "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:00Z",
  "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",
          }
        ],
      }
    ]
  },
)
Result Format
{
  "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
)

Line Item Attributes

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

AttributeRequired?DatatypeDescription
typeYesStringOne of either subscription or one_time.
subscription_external_idYes, for subscription line items.
Irrelevant for one_time line items.		StringA reference identifier for the subscription in your system. Accepts alphanumeric characters.
subscription_set_external_idNo. Only relevant for subscription line itemsStringA reference identifier for a set of subscriptions in order to group several subscriptions into one set.
plan_uuidYes, for subscription line items.
Optional for one_time line items.		StringThe ChartMogul UUID of the plan for which this subscription is being charged.
service_period_startYes, for subscription line items.
Irrelevant for one_time line items.		TimestampThe 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_endYes, for subscription line items.
Irrelevant for one_time line items.		TimestampThe 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_centsYesIntegerThe 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_atNo. Accepted for subscription line items.
Irrelevant for one_time line items.		TimestampIf 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.
proratedNo. Accepted for subscription line items.
Irrelevant for one_time line items.		BooleanIf this is a prorated charge, then set this attribute to true.
proration_typeNo. Accepted for subscription line items.
Irrelevant for one_time line items.		StringIf 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.
descriptionNo. Accepted for one_time line items.
Ignored for subscription line items.		StringA short description of the non-recurring item being charged to the customer.
quantityNoIntegerThe 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_centsNoIntegerIf 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_codeNoStringIf a discount has been applied to this line item, then an optional reference code to identify the discount.
tax_amount_in_centsNoIntegerThe 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_centsNoIntegerThe 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_idNoStringA unique identifier specified by you for the line item. Typically an identifier from your internal system. Accepts alphanumeric characters.
account_codeNoStringThe 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_currencyNoStringThe 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_descriptionNoStringA short description of discount_amount_in_cents.
event_orderNoIntegerUsed 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.

AttributeRequired?DatatypeDescription
dateYesTimestampThe 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.
typeYesStringEither one of payment or refund.
resultYesStringEither one of successful or failed.
amount_in_centsNoIntegerThe 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_idNoStringA 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 andprovided_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
Credentials
Basic
base64
: