Payment Plans

Payment plans allow you to collect an invoice balance over multiple installments. You can learn more about payment plans in our Payment Plans Guide.

Payment Plan Object

Describes and tracks the status of a payment plan.

Attributes

{
    "approval": {
        "id": 12,
        "ip": "217.15.151.36",
        "timestamp": 1479827803,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:50.0) Gecko/20100101 Firefox/50.0"
    },
    "created_at": 1479827791,
    "id": 6,
    "installments": [
        {
            "amount": 500,
            "balance": 500,
            "date": 1480572000,
            "id": 23
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1481176800,
            "id": 24
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1481781600,
            "id": 25
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1482386400,
            "id": 26
        }
    ],
    "object": "payment_plan",
    "status": "active",
    "updated_at": 1479827791
}

Parameter	Type	Description
id	integer	The payment plan's unique ID
object	string	Object type, `payment_plan`
status	string	Payment plan state, one of `pending_signup`, `active`, `finished`, `canceled`
installments	array	Payment plan installments
approval	object	Payment plan approval, if approved
created_at	timestamp	Timestamp when created
updated_at	timestamp	Timestamp when updated

Create a payment plan

curl "https://api.invoiced.com/invoices/:invoice_id/payment_plan" \
  -u {API_KEY}: \
  -X PUT \
  -d installments[0][date]=1480572000 \
  -d installments[0][amount]=500 \
  -d installments[1][date]=1481176800 \
  -d installments[1][amount]=500 \
  -d installments[2][date]=1481781600 \
  -d installments[2][amount]=500 \
  -d installments[3][date]=1480572000 \
  -d installments[3][amount]=500

invoice = invoiced.Invoice.retrieve("{INVOICE_ID}")
payment_plan = invoice.payment_plan.create(
  :installments => [
    {
      :date => 1480572000,
      :amount => 500
    },
    {
      :date => 1481176800,
      :amount => 500
    },
    {
      :date => 1481781600,
      :amount => 500
    },
    {
      :date => 1480572000,
      :amount => 500
    }
  ]
)

<?php

$invoice = $invoiced->Invoice->retrieve("{INVOICE_ID}");
$paymentPlan = $invoice->paymentPlan()->create([
  'installments' => [
    [
      'date' => 1480572000,
      'amount' => 500
    ],
    [
      'date' => 1481176800,
      'amount' => 500
    ],
    [
      'date' => 1481781600,
      'amount' => 500
    ],
    [
      'date' => 1480572000,
      'amount' => 500
    ]
  ]
]);

invoice = client.Invoice.retrieve("{INVOICE_ID}")
payment_plan = invoice.payment_plan().create(
  installments=[
    {
      'date': 1480572000,
      'amount': 500
    },
    {
      'date': 1481176800,
      'amount': 500
    },
    {
      'date': 1481781600,
      'amount': 500
    },
    {
      'date': 1480572000,
      'amount': 500
    }
  ]
)

Invoice invoice = invoiced.newInvoice().retrieve({INVOICE_ID});
PaymentPlan paymentPlan = invoice.newPaymentPlan();
Installment[] installments = new Installment[4];
installments[0] = new Installment();
installments[0].date = 1480572000L;
installments[0].amount = 500D;
installments[1] = new Installment();
installments[1].date = 1481176800L;
installments[1].amount = 500D;
installments[2] = new Installment();
installments[2].date = 1481781600L;
installments[2].amount = 500D;
installments[3] = new Installment();
installments[3].date = 1480572000L;
installments[3].amount = 500D;
paymentPlan.installments = installments;
paymentPlan.create();

var invoice = invoiced.NewInvoice().Retrieve({INVOICE_ID});
var paymentPlan = invoice.NewPaymentPlan();
var installments = new Installment[4];
installments[0] = new Installment();
installments[0].Date = 1480572000;
installments[0].Amount = 500;
installments[1] = new Installment();
installments[1].Date = 1481176800;
installments[1].Amount = 500;
installments[2] = new Installment();
installments[2].Date = 1481781600;
installments[2].Amount = 500;
installments[3] = new Installment();
installments[3].Date = 1480572000;
installments[3].Amount = 500;
paymentPlan.Installments = installments;
paymentPlan.Create();

paymentPlan, err := client.Invoice.CreatePaymentPlan({INVOICE_ID}, &invoiced.PaymentPlanRequest{
  Installments: []*invoiced.PaymentPlanInstallmentRequest{
    {
      Date: invoiced.Int64(1480572000),
      Amount: invoiced.Float64(500),
    },
    {
      Date: invoiced.Int64(1481176800),
      Amount: invoiced.Float64(500),
    },
    {
      Date: invoiced.Int64(1481781600),
      Amount: invoiced.Float64(500),
    },
    {
      Date: invoiced.Int64(1480572000),
      Amount: invoiced.Float64(500),
    },
  },
})

The above command returns JSON structured like this:

{
    "approval": {
        "id": 12,
        "ip": "217.15.151.36",
        "timestamp": 1479827803,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:50.0) Gecko/20100101 Firefox/50.0"
    },
    "created_at": 1479827791,
    "id": 6,
    "installments": [
        {
            "amount": 500,
            "balance": 500,
            "date": 1480572000,
            "id": 23
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1481176800,
            "id": 24
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1481781600,
            "id": 25
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1482386400,
            "id": 26
        }
    ],
    "object": "payment_plan",
    "status": "active",
    "updated_at": 1479827791
}

HTTP Request

PUT /invoices/:id/payment_plan

Attributes

Parameter	Type	Description
installments	array	Payment plan installments

Retrieve a payment plan

curl "https://api.invoiced.com/invoices/:invoice_id/payment_plan" \
  -u {API_KEY}:

invoice = invoiced.Invoice.retrieve("{INVOICE_ID}")
payment_plan = invoice.payment_plan.retrieve()

<?php

$invoice = $invoiced->Invoice->retrieve("{INVOICE_ID}");
$paymentPlan = $invoice->paymentPlan()->get();

invoice = client.Invoice.retrieve("{INVOICE_ID}")
payment_plan = invoice.payment_plan().retrieve()

Invoice invoice = invoiced.newInvoice().retrieve({INVOICE_ID});
PaymentPlan paymentPlan = invoice.newPaymentPlan().retrieve();

var invoice = invoiced.NewInvoice().Retrieve({INVOICE_ID});
var paymentPlan = invoice.NewPaymentPlan().Retrieve();

paymentPlan, err := client.Invoice.RetrievePaymentPlan({INVOICE_ID})

The above command returns JSON structured like this:

{
    "approval": {
        "id": 12,
        "ip": "217.15.151.36",
        "timestamp": 1479827803,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:50.0) Gecko/20100101 Firefox/50.0"
    },
    "created_at": 1479827791,
    "id": 6,
    "installments": [
        {
            "amount": 500,
            "balance": 500,
            "date": 1480572000,
            "id": 23
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1481176800,
            "id": 24
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1481781600,
            "id": 25
        },
        {
            "amount": 500,
            "balance": 500,
            "date": 1482386400,
            "id": 26
        }
    ],
    "object": "payment_plan",
    "status": "active",
    "updated_at": 1479827791
}

This endpoint retrieves the payment plan for a given invoice.

HTTP Request

GET /invoices/:id/payment_plan

Cancel a payment plan

curl "https://api.invoiced.com/invoices/:invoice_id/payment_plan" \
  -u {API_KEY}: \
  -X DELETE

payment_plan.cancel

<?php

$paymentPlan->cancel();

payment_plan.cancel()

paymentPlan.cancel();

paymentPlan.Cancel();

err := client.Invoice.CancelPaymentPlan({INVOICE_ID})

The above command returns 204 No Content

This endpoint cancels an active payment plan.

HTTP Request

DELETE /invoices/:id/payment_plan