Customers

Customers represent the entity you are billing, whether this is an organization or a individual. Each customer has an AutoPay setting. When AutoPay is enabled, any invoices issued for this customer will be charged to the customer's payment source. Currently we support debit / credit cards and bank accounts (via ACH) as payment sources.

Conversely, when AutoPay is disabled we will let your customers pay each invoice issued with one of the payment methods you accept.

Customer Object

Attributes

{
    "ach_gateway": null,
    "address1": null,
    "address2": null,
    "attention_to": null,
    "autopay": true,
    "autopay_delay_days": null,
    "avalara_entity_use_code": null,
    "avalara_exemption_number": null,
    "cc_gateway": null,
    "chase": true,
    "chasing_cadence": null,
    "city": null,
    "country": "US",
    "created_at": 1415222128,
    "credit_hold": false,
    "credit_limit": null,
    "currency": null,
    "email": "billing@acmecorp.com",
    "id": 15444,
    "language": null,
    "metadata": {
        "account_rep": "Jan",
        "icp_number": "1234567890"
    },
    "name": "Acme",
    "next_chase_step": null,
    "notes": null,
    "number": "CUST-0001",
    "object": "customer",
    "owner": null,
    "parent_customer": null,
    "payment_source": {
        "brand": "Visa",
        "exp_month": 2,
        "exp_year": 20,
        "funding": "credit",
        "id": 850,
        "last4": "4242",
        "object": "card"
    },
    "payment_terms": null,
    "phone": null,
    "postal_code": null,
    "sign_up_page": null,
    "sign_up_url": null,
    "state": null,
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/t3NmhUomra3g3ueSNnbtUgrr/pdf",
    "tax_id": null,
    "taxable": true,
    "taxes": [],
    "type": "company",
    "updated_at": 1415222128
}

Create a customer

curl "https://api.invoiced.com/customers" \
  -u {API_KEY}: \
  -d name="Acme" \
  -d email="billing@acmecorp.com" \
  -d payment_terms="NET 30" \
  -d type="company"

invoiced.Customer.create(
  :name => "Acme",
  :email => "billing@acmecorp.com",
  :payment_terms => "NET 30",
  :type => "company"
)

<?php

$invoiced->Customer->create([
  'name' => "Acme",
  'email' => "billing@acmecorp.com",
  'payment_terms' => "NET 30",
  'type' => "company"
]);

client.Customer.create(
  name="Acme",
  email="billing@acmecorp.com",
  payment_terms="NET 30",
  type="company"
)

Customer customer = invoiced.newCustomer();
customer.name = "Acme";
customer.email = "billing@acmecorp.com";
customer.paymentTerms = "NET 30";
customer.type = "company";
customer.create();

var customer = invoiced.NewCustomer();
customer.Name = "Acme";
customer.Email = "billing@acmecorp.com";
customer.PaymentTerms = "NET 30";
customer.Type = "company";
customer.Create();

customer, err := client.Customer.Create(&invoiced.CustomerRequest{
  Name: invoiced.String("Acme"),
  Email: invoiced.String("billing@acmecorp.com"),
  PaymentTerms: invoiced.String("NET 30"),
  Type: invoiced.String("company"),
})

The above command returns JSON structured like this:

{
    "ach_gateway": null,
    "address1": null,
    "address2": null,
    "attention_to": null,
    "autopay": false,
    "autopay_delay_days": null,
    "avalara_entity_use_code": null,
    "avalara_exemption_number": null,
    "cc_gateway": null,
    "chase": true,
    "chasing_cadence": null,
    "city": null,
    "country": "US",
    "created_at": 1415222128,
    "credit_hold": false,
    "credit_limit": null,
    "currency": null,
    "email": "billing@acmecorp.com",
    "id": 15444,
    "language": null,
    "metadata": [],
    "name": "Acme",
    "next_chase_step": null,
    "notes": null,
    "number": "CUST-0001",
    "object": "customer",
    "owner": null,
    "parent_customer": null,
    "payment_source": null,
    "payment_terms": "NET 30",
    "phone": null,
    "postal_code": null,
    "sign_up_page": null,
    "sign_up_url": null,
    "state": null,
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/t3NmhUomra3g3ueSNnbtUgrr/pdf",
    "tax_id": null,
    "taxable": true,
    "taxes": [],
    "type": "company",
    "updated_at": 1415222128
}

Create a new customer profile with this endpoint.

HTTP Request

POST /customers

Attributes

Retrieve a customer

curl "https://api.invoiced.com/customers/:id" \
  -u {API_KEY}:

customer = invoiced.Customer.retrieve("{CUSTOMER_ID}")

<?php

$customer = $invoiced->Customer->retrieve("{CUSTOMER_ID}");

customer = client.Customer.retrieve("{CUSTOMER_ID}")

Customer customer = invoiced.newCustomer().retrieve({CUSTOMER_ID});

var customer = invoiced.NewCustomer().Retrieve({CUSTOMER_ID});

customer, err := client.Customer.Retrieve({CUSTOMER_ID})

The above command returns JSON structured like this:

{
    "ach_gateway": null,
    "address1": "342 Amber St",
    "address2": null,
    "attention_to": "Sarah Fisher",
    "autopay": false,
    "autopay_delay_days": null,
    "avalara_entity_use_code": null,
    "avalara_exemption_number": null,
    "cc_gateway": null,
    "chase": true,
    "chasing_cadence": null,
    "city": "Hill Valley",
    "country": "US",
    "created_at": 1415222128,
    "credit_hold": false,
    "credit_limit": null,
    "currency": null,
    "email": "billing@acmecorp.com",
    "id": 15444,
    "language": null,
    "metadata": [],
    "name": "Acme",
    "next_chase_step": null,
    "notes": null,
    "number": "CUST-0001",
    "object": "customer",
    "owner": null,
    "parent_customer": null,
    "payment_source": null,
    "payment_terms": "NET 30",
    "phone": "(820) 297-2983",
    "postal_code": "94523",
    "sign_up_page": null,
    "sign_up_url": null,
    "state": "CA",
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/t3NmhUomra3g3ueSNnbtUgrr/pdf",
    "tax_id": "893-934835",
    "taxable": true,
    "taxes": [],
    "type": "company",
    "updated_at": 1415222128
}

This endpoint retrieves a specific customer.

HTTP Request

GET /customers/:id

Update a customer

curl "https://api.invoiced.com/customers/:id" \
  -u {API_KEY}: \
  -d payment_terms="NET 14" \
  -d attention_to="Sarah Fisher" \
  -d address1="342 Amber St" \
  -d city="Hill Valley" \
  -d state="CA" \
  -d postal_code="94523" \
  -d tax_id="893-934835" \
  -d phone="(820) 297-2983" \
  -X PATCH

customer.payment_terms = "NET 14"
customer.attention_to = "Sarah Fisher"
customer.address1 = "342 Amber St"
customer.city = "Hill Valley"
customer.state = "CA"
customer.postal_code = "94523"
customer.tax_id = "893-934835"
customer.phone = "(820) 297-2983"
customer.save

<?php

$customer->payment_terms = "NET 14";
$customer->attention_to = "Sarah Fisher";
$customer->address1 = "342 Amber St";
$customer->city = "Hill Valley";
$customer->state = "CA";
$customer->postal_code = "94523";
$customer->tax_id = "893-934835";
$customer->phone = "(820) 297-2983";
$customer->save();

customer.payment_terms = "NET 14"
customer.attention_to = "Sarah Fisher"
customer.address1 = "342 Amber St"
customer.city = "Hill Valley"
customer.state = "CA"
customer.postal_code = "94523"
customer.tax_id = "893-934835"
customer.phone = "(820) 297-2983"
customer.save()

customer.paymentTerms = "NET 14";
customer.attentionTo = "Sarah Fisher";
customer.address1 = "342 Amber St";
customer.city = "Hill Valley";
customer.state = "CA";
customer.postalCode = "94523";
customer.taxId = "893-934835";
customer.phone = "(820) 297-2983";
customer.save();

customer.PaymentTerms = "NET 14";
customer.AttentionTo = "Sarah Fisher";
customer.Address1 = "342 Amber St";
customer.City = "Hill Valley";
customer.State = "CA";
customer.PostalCode = "94523";
customer.TaxId = "893-934835";
customer.Phone = "(820) 297-2983";
customer.SaveAll();

customer, err := client.Customer.Update({CUSTOMER_ID}, &invoiced.CustomerRequest{
  PaymentTerms: invoiced.String("NET 14"),
  AttentionTo: invoiced.String("Sarah Fisher"),
  Address1: invoiced.String("342 Amber St"),
  City: invoiced.String("Hill Valley"),
  State: invoiced.String("CA"),
  PostalCode: invoiced.String("94523"),
  TaxId: invoiced.String("893-934835"),
  Phone: invoiced.String("(820) 297-2983"),
})

The above command returns JSON structured like this:

{
    "ach_gateway": null,
    "address1": "342 Amber St",
    "address2": null,
    "attention_to": "Sarah Fisher",
    "autopay": false,
    "autopay_delay_days": null,
    "avalara_entity_use_code": null,
    "avalara_exemption_number": null,
    "cc_gateway": null,
    "chase": true,
    "chasing_cadence": null,
    "city": "Hill Valley",
    "country": "US",
    "created_at": 1415222128,
    "credit_hold": false,
    "credit_limit": null,
    "currency": null,
    "email": "billing@acmecorp.com",
    "id": 15444,
    "language": null,
    "metadata": [],
    "name": "Acme",
    "next_chase_step": null,
    "notes": null,
    "number": "CUST-0001",
    "object": "customer",
    "owner": null,
    "parent_customer": null,
    "payment_source": null,
    "payment_terms": "NET 30",
    "phone": "(820) 297-2983",
    "postal_code": "94523",
    "sign_up_page": null,
    "sign_up_url": null,
    "state": "CA",
    "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/t3NmhUomra3g3ueSNnbtUgrr/pdf",
    "tax_id": "893-934835",
    "taxable": true,
    "taxes": [],
    "type": "company",
    "updated_at": 1415222128
}

Use this endpoint to update a customer profile.

HTTP Request

PATCH /customers/:id

Request Parameters

Get current balance

curl "https://api.invoiced.com/customers/balance" \
  -u {API_KEY}:

customer.balance

<?php

$customer->balance();

customer.balance()

Balance balance = customer.getBalance();

var balance = customer.GetBalance();

balance, err := client.Customer.GetBalance({CUSTOMER_ID})

The above command returns JSON structured like this:

{
    "available_credits": 50,
    "currency": "usd",
    "due_now": 0,
    "history": [
        {
            "balance": 50,
            "currency": "usd",
            "timestamp": 1464041624
        },
        {
            "balance": 100,
            "currency": "usd",
            "timestamp": 1464040550
        }
    ],
    "past_due": false,
    "total_outstanding": 470
}

This endpoint returns the customer's current credit balance, credit balance history, and the current amount outstanding.

HTTP Request

GET /customers/:id/balance

Query Parameters

Send a statement email

curl "https://api.invoiced.com/customers/:id/emails" \
  -u {API_KEY}: \
  -X POST

emails = customer.send_statement

<?php

$emails = $customer->sendStatement();

emails = customer.send_statement()

EmailRequest emailRequest = new EmailRequest();
EmailRecipient[] emailRecipients = new EmailRecipient[1];
emailRecipients[0] = new EmailRecipient();
emailRecipients[0].name = "Client";
emailRecipients[0].email = "client@example.com";
emailRequest.to = emailRecipients;
emailRequest.subject = "Statement from Dunder Mifflin, Inc.";
emailRequest.message = "Dear Client, we have attached your latest account statement. Thank you!";
Email[] emails = customer.sendStatement(emailRequest);

var emailRequest = new EmailRequest();
var emailRecipients = new EmailRecipient[1];
emailRecipients[0] = new EmailRecipient();
emailRecipients[0].Name = "Client";
emailRecipients[0].Email = "client@example.com";
emailRequest.To = emailRecipients;
emailRequest.Subject = "Statement from Dunder Mifflin, Inc.";
emailRequest.Message = "Dear Client, we have attached your latest account statement. Thank you!";
var emails = customer.SendStatementEmail(emailRequest);

err := client.Customer.SendStatementEmail({CUSTOMER_ID}, &invoiced.SendStatementEmailRequest{
  To: []*invoiced.EmailRecipient{
    Name: invoiced.String("Client"),
    Email: "client@example.com",
  },
  Subject: invoiced.String("Statement from Dunder Mifflin, Inc."),
  Message: invoiced.String("Dear Client, we have attached your latest account statement. Thank you!"),
})

The above command returns JSON structured like this:

[
  {
     "created_at": 1436890047,
     "email": "client@example.com",
     "id": "f45382c6fbc44d44aa7f9a55eb2ce731",
     "message": "Dear Client, we have attached your latest account statement. Thank you!",
     "object": "email",
     "opens": 0,
     "opens_detail": [],
     "reject_reason": null,
     "state": "sent",
     "subject": "Statement from Dunder Mifflin, Inc.",
     "template": "statement_email",
     "updated_at": 1436890047
 }
]

This endpoint sends a PDF account statement to a customer by email.

HTTP Request

POST /customers/:id/emails

Request Parameters

Send a statement SMS

curl "https://api.invoiced.com/customers/:id/text_messages" \
  -u {API_KEY}: \
  -d to[0][phone]="11234567890" \
  -d to[0][name]="Bob Loblaw" \
  -d message="{{company_name}}: You have a new statement {{url}}"
  -d type="open_item" \
  -X POST

text_messages = customer.send_statement_text(
  :type => "open_item",
  :to => [{"phone" => "11234567890", "name" => "Bob Loblaw"}],
  :message => "{{company_name}}: You have a new statement {{url}}")

<?php

$textMessages = $customer->sendStatementText([
  'type' => 'open_item',
  'to' => [['phone' => "11234567890", 'name' => "Bob Loblaw"]],
  'message' => "{{company_name}}: You have a new statement {{url}}"]);

text_messages = customer.send_statement_text(
  type="open_item",
  to=[{"phone": "11234567890", "name": "Bob Loblaw"}],
  message="{{company_name}}: You have a new statement {{url}}")

TextRequest textRequest = new TextRequest();
TextRecipient recipient = new TextRecipient();
recipient.name = "Bob Loblaw";
recipient.phone = "11234567890";
textRequest.to = new TextRecipient[]{recipient};
textRequest.message = "{{company_name}}: You have a new statement {{url}}";
textRequest.type = "open_item";
TextMessage[] textMessages = customer.sendStatementText(textRequest);

var textRequest = new TextRequest();
var recipient = new TextRecipient();
recipient.Name = "Bob Loblaw";
recipient.Phone = "11234567890";
textRequest.To = new TextRecipient[]{recipient};
textRequest.Message = "{{company_name}}: You have a new statement {{url}}";
textRequest.Type = "open_item";
var textMessages = customer.SendStatementText(textRequest);

texts, err := client.Customer.SendStatementText(&invoiced.SendStatementTextMessageRequest{
  To: []*invoiced.TextMessageRecipient{
    {
      Name: invoiced.String("Bob Loblaw"),
      Phone: invoiced.String("11234567890"),
    }
  }
  Type: invoiced.String("open_item"),
  Message: invoiced.String("{{company_name}}: You have a new statement {{url}}"),
})

The above command returns JSON structured like this:

[
  {
     "created_at": 1571086718,
     "id": "c05c9cae8c5799da1e5723a0fff355b3",
     "message": "Acme Inc.: You have a new statement https://acme.invoiced.com/statements/5X5g7Sb46KIR9IzxjjEjdnI9",
     "state": "sent",
     "to": "+15125551212",
     "updated_at": 1571086718
 }
]

This endpoint sends an account statement by SMS to a customer using Twilio. Twilio must be connected to Invoiced for requests to succeed.

Text messages can only be sent to customer contacts marked as sms_enabled.

HTTP Request

POST /customers/:id/text_messages

Request Parameters

Send a statement letter

curl "https://api.invoiced.com/customers/:id/letters" \
  -u {API_KEY}: \
  -d type="open_item" \
  -X POST

letters = customer.send_statement_letter

<?php

$letters = $customer->sendStatementLetter();

letters = customer.send_statement_letter()

LetterRequest letterRequest = new LetterRequest();
letterRequest.type = "open_item";
Letter letters = customer.sendStatementLetter(letterRequest);

var letterRequest = new LetterRequest();
letterRequest.Type = "open_item";
var letter = customer.SendStatementLetter(letterRequest);

letter, err := client.Customer.SendStatementLetter(&invoiced.SendStatementLetterRequest{
  Type: invoiced.String("open_item"),
})

The above command returns JSON structured like this:

{
    "created_at": 1570826337,
    "expected_delivery_date": 1571776737,
    "id": "2678c1e7e6dd1011ce13fb6b76db42df",
    "num_pages": 1,
    "state": "queued",
    "to": "Acme Inc.\n5301 Southwest Pkwy\nAustin, TX 78735",
    "updated_at": 1570826337
}

This endpoint sends an account statement by mail to a customer using Lob. Lob must be connected to Invoiced for requests to succeed.

The letter will automatically be sent to the customer's billing address.

HTTP Request

POST /customers/:id/letters

Request Parameters

Delete a customer

curl "https://api.invoiced.com/customers/:id" \
  -u {API_KEY}: \
  -X DELETE

customer.delete

<?php

$customer->delete();

customer.delete()

customer.delete();

customer.Delete();

err := invoiced.Customer.Delete({CUSTOMER_ID})

The above command returns 204 No Content

This endpoint deletes a specific customer.

HTTP Request

DELETE /customers/:id

List all customers

curl "https://api.invoiced.com/customers" \
  -u {API_KEY}:

customers, metadata = invoiced.Customer.list(:per_page => 3)

<?php

list($customers, $metadata) = $invoiced->Customer->all(['per_page' => 3]);

customers, metadata = client.Customer.list(per_page=3)

EntityList<Customer> customers = connection.newCustomer().listAll();

var customers = invoiced.NewCustomer().ListAll();

customers, err := client.Customer.ListAll(nil, nil)

The above command returns JSON structured like this:

[
  {
     "ach_gateway": null,
     "address1": "342 Amber St",
     "address2": null,
     "attention_to": "Sarah Fisher",
     "autopay": false,
     "autopay_delay_days": null,
     "avalara_entity_use_code": null,
     "avalara_exemption_number": null,
     "cc_gateway": null,
     "chase": true,
     "chasing_cadence": null,
     "city": "Hill Valley",
     "country": "US",
     "created_at": 1415222128,
     "credit_hold": false,
     "credit_limit": null,
     "currency": null,
     "email": "billing@acmecorp.com",
     "id": 15444,
     "language": null,
     "metadata": [],
     "name": "Acme",
     "next_chase_step": null,
     "notes": null,
     "number": "CUST-0001",
     "object": "customer",
     "owner": null,
     "parent_customer": null,
     "payment_source": null,
     "payment_terms": "NET 30",
     "phone": "(820) 297-2983",
     "postal_code": "94523",
     "sign_up_page": null,
     "sign_up_url": null,
     "state": "CA",
     "statement_pdf_url": "https://dundermifflin.invoiced.com/statements/t3NmhUomra3g3ueSNnbtUgrr/pdf",
     "tax_id": "893-934835",
     "taxable": true,
     "taxes": [],
     "type": "company",
     "updated_at": 1415222128
 }
]

This endpoint retrieves all customers.

HTTP Request

GET /customers

Query Parameters