Introduction
Invoiced is simple invoicing for freelancers and small businesses. Our HTTP API was designed to be easy to integrate into your workflow.
We have done our best to follow REST principles when designing the API.
API Endpoint
All API calls must be made to https://api.invoiced.com
.
JSON-only
All responses will be in JSON. Input data passed through the request body can be form-encoded or JSON-encoded. If using a JSON body, please specify the Content-Type
header as application/json
.
In the API dates are represented as UNIX timestamps. Each entity like customers or invoices has a unique integer id.
Client Libraries
We have client libraries available in several languages. If you don’t see your language listed then please contact us and we would be happy to help.
Getting Help or Contributing
We’ve made this document open source. Please report any issues or suggestions in the issues. If you need help using the API or need to discuss anything sensitive please message us at api@invoiced.com. Any pull requests to improve this document are welcome too!
Authentication
The API uses HTTP Basic Authentication to authenticate users. A valid API key is required for all requests.
Obtaining an API Key
An API key can be obtained by signing in to invoiced.com, and then going to Settings > API Keys. Each business on Invoiced has its own set of API keys. We recommend creating a separate API key for each application that will be making calls on your behalf.
Usage
curl https://api.invoiced.com/invoices \
-u {YOUR_API_KEY}:
require "invoiced"
invoiced = Invoiced::Client.new("{YOUR_API_KEY}")
<?php
$invoiced = new Invoiced\Client("{YOUR_API_KEY}");
The API key must be passed in through the username with the password left blank. The right sidebar has an example request with authorization
Errors
Each API call returns an HTTP status code that reflects the nature of the response. We have done our best to follow the HTTP status code conventions.
Any request that did not succeed will return a 4xx or 5xx error. The 4xx range means there was a problem with the request, like a missing parameter. The 5xx range means that something went wrong on our end.
The Invoiced API returns the following HTTP status codes:
200 OK – Request succeeded
201 Created – A resource was created
204 No Content – Request succeeded but there is no response body
400 Bad Request – Invalid request parameters
401 Unauthorized – Incorrect or missing API key
403 Forbidden – You do not have permission to view a resource or perform an action
404 Not Found – The specified resource could not be found
429 Too Many Requests – You’re moving too fast! Slow down!
500 Internal Server Error – There was a problem on our end
All error responses will contain an object with these attributes
Parameter | Description |
---|---|
type | Type of error, invalid_request or api |
message | Explanation of the error |
param | Available when a specific request parameter was responsible |
Pagination
Link: <https://api.invoiced.com/customers?page=3&per_page=10>; rel="self",
<https://api.invoiced.com/customers?page=1&per_page=10>; rel="first",
<https://api.invoiced.com/customers?page=2&per_page=10>; rel="previous",
<https://api.invoiced.com/customers?page=4&per_page=10>; rel="next",
<https://api.invoiced.com/customers?page=5&per_page=10>; rel="last"
All list operations will be paginated in similar fashion as the GitHub API. In most cases we will paginate requests returning more than 100 results. You can control pagination with the page
and per_page
parameters. Pages start at 1
and the first page will be returned if no page is specified.
When traversing the pages, we recommend using the Link
and X-Total-Count
headers. The Link header will return URLs that you can use to traverse the API without having to write your own. It’s preferred to use the links from the API because it protects against future updates.
Versioning
Any future changes to the API will be versioned in order to maintain backwards compatibility with existing integrations.
Special Parameters
Expanding Relations
Usually you need to request more than just an invoice. Often, you might want data about the associated customer. There is a built-in way to do this that saves extra API requests.
Certain relational properties can be expanded by passing in a comma-separated list of properties to expand through the expand
parameter. For example if you were requesting a payment and wanted to expand the associated customer and invoice objects you would set expand=customer,invoice
. This will replace the ID on the customer
and invoice
properties with expanded objects.
The expand
parameter works for any response that has relational properties.
Filter
"filter": {
"paid": false,
"customer": 1234
}
:filter => {
:paid => false,
:customer => 1234
}
"filter" => [
"paid" => false,
"customer" => 1234
]
The filter
parameter allows you to search entities based on an exact match. While it is not meant to replace a search API, the filter
parameter can be useful if you need to look up a customer by name or want to list all overdue invoices. It can be used on many of the list endpoints.
The filter
parameter is an object whose keys are the properties that should be matched:
Customers
Customers represent the entity you are billing, whether this is an organization or a individual. Each customer has a collection mode, automatic or manual. In automatic collection mode any invoices will be charged to your customer’s payment source. Currently we only support debit and credit cards as payment sources.
Conversely, manual collection mode will let your customers pay each invoice issued with one of the payment methods you accept.
Customer Object
Attributes
{
"id": 15444,
"name": "Acme",
"number": "CUST-0001",
"email": "billing@acmecorp.com",
"type": "company",
"collection_mode": "auto",
"payment_terms": null,
"payment_source": {
"id": 850,
"brand": "Visa",
"last4": 4242,
"exp_month": 2,
"exp_year": 20,
"funding": "credit"
},
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
"id": 15444,
"name": "Acme",
"number": "CUST-0001",
"email": "billing@acmecorp.com",
"type": "company",
"collection_mode": "auto",
"payment_terms": null,
"payment_source": {
"id": 850,
"brand": "Visa",
"last4": 4242,
"exp_month": 2,
"exp_year": 20,
"funding": "credit"
},
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Invoiced\Customer JSON: {
"id": 15444,
"name": "Acme",
"number": "CUST-0001",
"email": "billing@acmecorp.com",
"type": "company",
"collection_mode": "auto",
"payment_terms": null,
"payment_source": {
"id": 850,
"brand": "Visa",
"last4": 4242,
"exp_month": 2,
"exp_year": 20,
"funding": "credit"
},
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Parameter | Type | Description |
---|---|---|
id | integer | The customer’s unique ID |
name | string | Customer name |
number | string | The reference number assigned to the customer for use in the dashboard |
type | string | Organization type, company or person |
string | Email address | |
collection_mode | string | Invoice collection mode, auto or manual |
payment_terms | string | Payment terms used for manual collection mode, i.e. “NET 30” |
payment_source | object | Summary of the customer’s payment source, if attached |
attention_to | string | Used for ATTN: address line if company |
address1 | string | First address line |
address2 | string | Optional second address line |
city | string | City |
state | string | State or province |
postal_code | string | Zip or postal code |
country | string | Country |
tax_id | string | Tax ID to be displayed on documents |
phone | string | Phone # |
other_phone | string | Second phone # |
website | string | Website |
notes | string | Private customer notes |
statement_pdf_url | string | URL to download the latest account statement |
created_at | timestamp | Timestamp when created |
Create a customer
curl "https://api.invoiced.com/customers" \
-u {API_KEY}: \
-d name="Acme" \
-d email="billing@acmecorp.com" \
-d collection_mode="manual" \
-d payment_terms="NET 30" \
-d type="company"
invoiced.Customer.create(
:name => "Acme",
:email => "billing@acmecorp.com",
:collection_mode => "manual",
:payment_terms => "NET 30",
:type => "company"
)
<?php
$invoiced->Customer->create([
'name' => "Acme",
'email' => "billing@acmecorp.com",
'collection_mode' => "manual",
'payment_terms' => "NET 30",
'type' => "company"
]);
The above command returns JSON structured like this:
{
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Invoiced\Customer JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Create a new customer profile with this endpoint.
HTTP Request
POST /customers
Attributes
Parameter | Type | Description |
---|---|---|
name | string | Customer name - required |
number | string | The reference number assigned to the customer for use in the dashboard. We will generate one if not supplied. |
type | string | Organization type, company or person . Defaults to company |
string | Email address | |
collection_mode | string | Invoice collection mode, auto or manual . Defaults to manual |
payment_terms | string | Payment terms used for manual collection mode, i.e. “NET 30” |
stripe_token | string | When provided sets the customer’s payment source to the tokenized Stripe card |
attention_to | string | Used for ATTN: address line if company |
address1 | string | First address line |
address2 | string | Optional second address line |
city | string | City |
state | string | State or province |
postal_code | string | Zip or postal code |
country | string | Country |
tax_id | string | Tax ID to be displayed on documents |
phone | string | Phone # |
other_phone | string | Second phone # |
website | string | Website |
notes | string | Private customer notes |
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}");
The above command returns JSON structured like this:
{
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Invoiced\Customer JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"postal_code": null,
"country": "United States",
"tax_id": null,
"phone": null,
"other_phone": null,
"website": null,
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_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" \
-d website="acmecorp.com" \
-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.website = "acmecorp.com"
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->website = "acmecorp.com";
$customer->save();
The above command returns JSON structured like this:
{
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 14",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 14",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Invoiced\Customer JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 14",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
}
Use this endpoint to update a customer profile.
HTTP Request
PATCH /customers/:id
Request Parameters
Parameter | Type | Description |
---|---|---|
name | string | Customer name |
number | string | The reference number assigned to the customer for use in the dashboard |
type | string | Organization type, company or person |
string | Email address | |
collection_mode | string | Invoice collection mode, auto or manual |
payment_terms | string | Payment terms used for manual collection mode, i.e. “NET 30” |
stripe_token | string | When provided sets the customer’s payment source to the tokenized Stripe card |
attention_to | string | Used for ATTN: address line if company |
address1 | string | First address line |
address2 | string | Optional second address line |
city | string | City |
state | string | State or province |
postal_code | string | Zip or postal code |
country | string | Country |
tax_id | string | Tax ID to be displayed on documents |
phone | string | Phone # |
other_phone | string | Second phone # |
website | string | Website |
notes | string | Private customer notes |
List customer subscriptions
curl "https://api.invoiced.com/customers/:id/subscriptions" \
-u {API_KEY}:
subscriptions, metadata = customer.subscriptions
<?php
list($subscriptions, $metadata) = $customer->subscriptions();
The above command returns JSON structured like this:
[
{
"id": 412,
"customer": 15444,
"plan": 418,
"start_date": 1415230038,
"quantity": 1,
"cycles": null,
"renews_next": 1438813638,
"renewed_last": 1436135238,
"status": "past_due",
"url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ClfLz70YiFSgu5E2dA5qrwXX",
"created_at": 1415230041
},
{
"id": 595,
"customer": 15444,
"plan": 420,
"start_date": 1425572792,
"quantity": 1,
"cycles": null,
"renews_next": 1438788392,
"renewed_last": 1436109992,
"status": "active",
"url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ir5n8vGRTcsJyBNS8lzR6gXX",
"created_at": 1425572798
}
]
[
#<Invoiced::Subscription:0x3fdbf9sf9e4d08 id=412> JSON: {
"id": 412,
"customer": 15444,
"plan": 418,
"start_date": 1415230038,
"quantity": 1,
"cycles": null,
"renews_next": 1438813638,
"renewed_last": 1436135238,
"status": "past_due",
"url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ClfLz70YiFSgu5E2dA5qrwXX",
"created_at": 1415230041
},
#<Invoiced::Subscription:0x3fdbf95as4d08 id=595> JSON: {
"id": 595,
"customer": 15444,
"plan": 420,
"start_date": 1425572792,
"quantity": 1,
"cycles": null,
"renews_next": 1438788392,
"renewed_last": 1436109992,
"status": "active",
"url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ir5n8vGRTcsJyBNS8lzR6gXX",
"created_at": 1425572798
}
]
[
Invoiced\Subscription JSON: {
"id": 412,
"customer": 15444,
"plan": 418,
"start_date": 1415230038,
"quantity": 1,
"cycles": null,
"renews_next": 1438813638,
"renewed_last": 1436135238,
"status": "past_due",
"url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ClfLz70YiFSgu5E2dA5qrwXX",
"created_at": 1415230041
},
Invoiced\Subscription JSON: {
"id": 595,
"customer": 15444,
"plan": 420,
"start_date": 1425572792,
"quantity": 1,
"cycles": null,
"renews_next": 1438788392,
"renewed_last": 1436109992,
"status": "active",
"url": "https:\/\/dundermifflin.invoiced.com\/subscriptions\/ir5n8vGRTcsJyBNS8lzR6gXX",
"created_at": 1425572798
}
]
This endpoint lists all the subscriptions for a specific customer.
HTTP Request
GET /customers/:id/subscriptions
Query Parameters
Parameter | Type | Description |
---|---|---|
expand | string | Properties to expand |
Get current balance
curl "https://api.invoiced.com/customers/balance" \
-u {API_KEY}:
customer.balance
<?php
$customer->balance();
The above command returns JSON structured like this:
{
"available_credits": 50,
"past_due": false,
"total_outstanding": 470
}
{
:available_credits => 50,
:past_due => false,
:total_outstanding => 470
}
stdClass {
"available_credits": 50,
"past_due": false,
"total_outstanding": 470
}
This endpoint calculates the customer’s current balance.
HTTP Request
GET /customers/:id/balance
Send a statement
curl "https://api.invoiced.com/customers/:id/emails" \
-u {API_KEY}: \
-X POST
emails = customer.send_statement
<?php
$emails = $customer->sendStatement();
The above command returns JSON structured like this:
[
{
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "statement_email",
"subject": "Statement from Dunder Mifflin, Inc.",
"message": "Dear Client, we have attached your latest account statement. Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
{ ... },
{ ... }
]
[
#<Invoiced::Email:0x3fdbf95e4d08 id="f45382c6fbc44d44aa7f9a55eb2ce731"> JSON: {
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "statement_email",
"subject": "Statement from Dunder Mifflin, Inc.",
"message": "Dear Client, we have attached your latest account statement. Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
#<Invoiced::Email:0x3fdasdf95e09 id="a0s36fbc44d44aa7f9a55easdfi8ce731"> JSON: { ... },
#<Invoiced::Email:0x3fdbffge4d10 id="s90f2c6fbc44sdfj8aa7f9a55eb2ce731"> JSON: { ... }
]
[
Invoiced\Email JSON: {
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "statement_email",
"subject": "Statement from Dunder Mifflin, Inc.",
"message": "Dear Client, we have attached your latest account statement. Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
Invoiced\Email JSON: { ... },
Invoiced\Email JSON: { ... }
]
This endpoint sends a PDF account statement to a customer.
HTTP Request
POST /customers/:id/emails
Request Parameters
Parameter | Type | Description |
---|---|---|
to | array | Optional array of recipients like:[{"name": "Client", "email": "client@example.com"}] |
bcc | string | Optional comma-separated list of email addresses to be blind carbon copied |
subject | string | Optional subject |
message | string | Optional message body, otherwise the Statement Email template is used |
Delete a customer
curl "https://api.invoiced.com/customers/:id" \
-u {API_KEY}: \
-X DELETE
customer.delete
<?php
$customer->delete();
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->list(['per_page' => 3]);
The above command returns JSON structured like this:
[
{
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
},
{ ... },
{ ... }
]
[
#<Invoiced::Customer:0x3fdbf95e4d08 id=15444> JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
},
#<Invoiced::Customer:0x3fdbf95e4d09 id=15445> JSON: { ... },
#<Invoiced::Customer:0x3fdbf95e4d10 id=15446> JSON: { ... }
]
[
Invoiced\Customer JSON: {
"id": 15444,
"number": "CUST-0001",
"name": "Acme",
"email": "billing@acmecorp.com",
"collection_mode": "manual",
"payment_terms": "NET 30",
"payment_source": null,
"type": "company",
"attention_to": "Sarah Fisher",
"address1": "342 Amber St",
"address2": null,
"city": "Hill Valley",
"state": "CA",
"postal_code": "94523",
"country": "United States",
"tax_id": "893-934835",
"phone": "(820) 297-2983",
"other_phone": null,
"website": "acmecorp.com",
"notes": null,
"statement_pdf_url": "https://dundermifflin.invoiced.com/statements/15444/pdf",
"created_at": 1415222128
},
Invoiced\Customer JSON: { ... },
Invoiced\Customer JSON: { ... }
]
This endpoint retrieves all customers.
HTTP Request
GET /customers
Query Parameters
Parameter | Description |
---|---|
sort string | Column to sort by, i.e. name asc |
filter object | Filter object |
Invoices
An invoice representeds a balance owed to you by a Customer. Each invoice has a collection of line items that detail the products or services that are now due. An invoice can be in one of many different states depending on the due date, payments, and whether it was sent to or viewed by the customer.
Invoices can be marked as paid with Transactions. Once the sum of all Transactions for an invoice is greater than or equal to the total then the invoice will be considered paid in full.
Invoice Object
Attributes
{
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Invoiced\Invoice JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Parameter | Type | Description |
---|---|---|
id | integer | The invoice’s unique ID |
customer | integer | Customer ID |
name | string | Invoice name for internal use, defaults to “Invoice” |
number | string | The reference number assigned to the invoice for use in the dashboard |
collection_mode | string | Invoice collection mode, auto or manual |
currency | string | 3-digit ISO 4217 currency code |
draft | boolean | When false, the invoice is considered outstanding, or when true, the invoice is a draft |
sent | boolean | Indicates whether the invoice has been sent |
closed | boolean | When true, an invoice is closed and considered bad debt. No further payments are allowed. |
paid | boolean | Indicates whether an invoice has been paid in full |
status | string | Invoice state, one of draft , not_sent , sent , viewed , past_due , pending , paid , or overpaid |
chase | boolean | Whether chasing is enabled for the invoice |
next_chase_on | timestamp | Next scheduled chase |
attempt_count | integer | # of payment attempts |
next_payment_attempt | timestamp | Next scheduled charge attempt, when in automatic collection |
theme | integer | Theme ID for rendering with custom themes |
subscription | integer | Subscription ID if invoice came from subscription |
date | timestamp | Invoice date |
due_date | timestamp | Date payment is due by |
payment_terms | string | Payment terms for the invoice, i.e. “NET 30” |
items | array | Collection of Line Item objects |
terms | string | Terms and conditions displayed on invoice |
notes | string | Additional notes displayed on invoice |
subtotal | number | Subtotal |
discounts | array | Collection of Discount objects |
taxes | array | Collection of Tax objects |
total | number | Total |
balance | number | Balance |
url | string | URL to view the invoice in the billing portal |
pdf_url | string | URL to download the invoice as a PDF |
created_at | timestamp | Timestamp when created |
Line Item Object
Attributes
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
#<Invoiced::LineItem:0x3fdbf95e4d08 id=8> JSON: {
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
Invoiced\LineItem JSON: {
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
Parameter | Type | Description |
---|---|---|
id | integer | The line item’s unique ID |
stored_item | integer | Stored Item ID this line is associated with, if any |
plan | integer | Plan ID the line item was generated from |
type | string | Line item type, one of product , service , hours , days , or expense |
name | string | Title |
description | string | Optional description |
quantity | number | Quantity |
unit_cost | number | Unit cost or rate |
amount | number | Computed from quantity x unit_cost |
discounts | array | Line item Discounts |
taxes | array | Line item Taxes |
Discount Object
Attributes
{
"id": 20553,
"amount": 5,
"rate": null
}
#<Invoiced::Discount:0x3fdbf95e4d08 id=20553> JSON: {
"id": 20553,
"amount": 5,
"rate": null
}
Invoiced\Discount JSON: {
"id": 20553,
"amount": 5,
"rate": null
}
Parameter | Type | Description |
---|---|---|
id | integer | The discount’s unique ID |
amount | number | Discount amount |
rate | object | Discount Rate the discount was computed from, if any |
Tax Object
Attributes
{
"id": 20554,
"amount": 3.85,
"rate": null
}
#<Invoiced::Tax:0x3fdbf95e4d08 id=20554> JSON: {
"id": 20554,
"amount": 3.85,
"rate": null
}
Invoiced\Tax JSON: {
"id": 20554,
"amount": 3.85,
"rate": null
}
Parameter | Type | Description |
---|---|---|
id | integer | The tax’s unique ID |
amount | number | Tax amount |
rate | object | Tax Rate the tax was computed from, if any |
Create an invoice
curl "https://api.invoiced.com/invoices" \
-u {API_KEY}: \
-d customer=15444 \
-d payment_terms="NET 14" \
-d items[0][name]="Copy paper, Case" \
-d items[0][quantity]=1 \
-d items[0][unit_cost]=45 \
-d items[1][type]="service" \
-d items[1][name]="Delivery" \
-d items[1][quantity]=1 \
-d items[1][unit_cost]=10 \
-d taxes[0][amount]=3.85
invoiced.Invoice.create(
:customer => 15444,
:payment_terms => "NET 14",
:items => [
{
:name => "Copy paper, Case",
:quantity => 1,
:unit_cost => 45
},
{
:type => "service",
:name => "Delivery",
:quantity => 1,
:unit_cost => 45
}
],
:taxes => [
{
:amount => 3.85
}
]
)
<?php
$invoice = $invoiced->Invoice->create([
'customer' => 15444,
'payment_terms' => "NET 14",
'items' => [
[
'name' => "Copy paper, Case",
'quantity' => 1,
'unit_cost' => 45
],
[
'type' => "service",
'name' => "Delivery",
'quantity' => 1,
'unit_cost' => 45
]
],
'taxes' => [
[
'amount' => 3.85
]
]
]);
The above command returns JSON structured like this:
{
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Invoiced\Invoice JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Create a new invoice with this endpoint.
HTTP Request
POST /invoices
Attributes
Parameter | Type | Description |
---|---|---|
customer | integer | Customer ID - required |
name | string | Invoice name for internal use, defaults to “Invoice” |
number | string | The reference number assigned to the invoice, defaults to next # in auto-numbering sequence |
currency | string | 3-digit ISO 4217 currency code - defaults to account currency |
collection_mode | string | Invoice collection mode, auto or manual - inherited from customer by default |
payment_terms | string | Payment terms for the invoice, i.e. “NET 30” - inherited from customer by default |
date | timestamp | Invoice date - defaults to current timestamp |
due_date | timestamp | Due date - computed from payment_terms when not supplied |
draft | boolean | When false, the invoice is considered outstanding, or when true, the invoice is a draft |
sent | boolean | Marks an invoice as sent |
closed | boolean | Marks an invoice as closed |
chase | boolean | Enables chasing for this invoice |
theme | integer | Theme ID for rendering with custom themes |
items | array | Collection of Line Item objects |
terms | string | Terms and conditions displayed on invoice |
notes | string | Additional notes displayed on invoice |
discounts | array | Collection of Discount objects |
taxes | array | Collection of Tax objects |
Retrieve an invoice
curl "https://api.invoiced.com/invoices/:id" \
-u {API_KEY}:
invoice = invoiced.Invoice.retrieve("{INVOICE_ID}")
<?php
$invoice = $invoiced->Invoice->retrieve("{INVOICE_ID}");
The above command returns JSON structured like this:
{
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Invoiced\Invoice JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
This endpoint retrieves a specific invoice.
HTTP Request
GET /invoices/:id
Query Parameters
Parameter | Type | Description |
---|---|---|
expand | string | Properties to expand |
Update an invoice
curl "https://api.invoiced.com/invoices/:id" \
-u {API_KEY}: \
-X PATCH \
-d sent=1 \
-d chase=1
invoice.name = "July Paper Delivery"
invoice.notes = "The order was delivered on Jul 20, 2015"
invoice.sent = true
invoice.save
<?php
$invoice->name = "July Paper Delivery";
$invoice->notes = "The order was delivered on Jul 20, 2015";
$invoice->sent = true;
$invoice->save();
The above command returns JSON structured like this:
{
"id": 46225,
"customer": 15444,
"name": "July Paper Delivery",
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": "The order was delivered on Jul 20, 2015",
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Invoiced\Invoice JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
}
Use this endpoint to update an invoice.
HTTP Request
PATCH /invoices/:id
Attributes
Parameter | Type | Description |
---|---|---|
name | string | Invoice name for internal use, defaults to “Invoice” |
number | string | The reference number assigned to the invoice, defaults to next # in auto-numbering sequence |
currency | string | 3-digit ISO 4217 currency code - defaults to account currency |
payment_terms | string | Payment terms for the invoice, i.e. “NET 30” - inherited from customer by default |
date | timestamp | Invoice date - defaults to current timestamp |
due_date | timestamp | Due date - computed from payment_terms when not supplied |
draft | boolean | When false, the invoice is considered outstanding, or when true, the invoice is a draft |
sent | boolean | Marks an invoice as sent |
closed | boolean | Marks an invoice as closed |
chase | boolean | Enables chasing for this invoice |
theme | integer | Theme ID for rendering with custom themes |
items | array | Collection of Line Item objects |
terms | string | Terms and conditions displayed on invoice |
notes | string | Additional notes displayed on invoice |
discounts | array | Collection of Discount objects |
taxes | array | Collection of Tax objects |
Send an invoice
curl "https://api.invoiced.com/invoices/:id/emails" \
-u {API_KEY}: \
-X POST
emails = invoice.send
<?php
$emails = $invoice->send();
The above command returns JSON structured like this:
[
{
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "new_invoice_email",
"subject": "New Invoice from Dunder Mifflin, Inc.: INV-0016",
"message": "Dear Client, a new invoice for $51.15 has been created on your account. [View and Pay Invoice button] Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
{ ... },
{ ... }
]
[
#<Invoiced::Email:0x3fdbf95e4d08 id="f45382c6fbc44d44aa7f9a55eb2ce731"> JSON: {
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "new_invoice_email",
"subject": "New Invoice from Dunder Mifflin, Inc.: INV-0016",
"message": "Dear Client, a new invoice for $51.15 has been created on your account. [View and Pay Invoice button] Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
#<Invoiced::Email:0x3fdasdf95e09 id="a0s36fbc44d44aa7f9a55easdfi8ce731"> JSON: { ... },
#<Invoiced::Email:0x3fdbffge4d10 id="s90f2c6fbc44sdfj8aa7f9a55eb2ce731"> JSON: { ... }
]
[
Invoiced\Email JSON: {
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "new_invoice_email",
"subject": "New Invoice from Dunder Mifflin, Inc.: INV-0016",
"message": "Dear Client, a new invoice for $51.15 has been created on your account. [View and Pay Invoice button] Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
Invoiced\Email JSON: { ... },
Invoiced\Email JSON: { ... }
]
This endpoint sends an invoice to your customer.
HTTP Request
POST /invoices/:id/emails
Request Parameters
Parameter | Type | Description |
---|---|---|
to | array | Optional array of recipients like:[{"name": "Client", "email": "client@example.com"}] |
bcc | string | Optional comma-separated list of email addresses to be blind carbon copied |
subject | string | Optional subject |
message | string | Optional message body, otherwise the appropriate invoice template is used |
Pay an invoice
curl "https://api.invoiced.com/invoices/:id/pay" \
-u {API_KEY}: \
-X POST
invoice.pay
<?php
$invoice->pay();
The above command returns JSON structured like this:
{
"id": 46226,
"customer": 15446,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": true,
"status": "paid",
"chase": false,
"next_chase_on": null,
"collection_mode": "auto",
"attempt_count": 1,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0017",
"date": 1416290402,
"due_date": null,
"payment_terms": "Auto-Charged",
"items": [
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 5,
"unit_cost": 45,
"amount": 225,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 225,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 228.85,
"balance": 228.85,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ/pdf",
"created_at": 1415229885
}
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46226> JSON: {
"id": 46226,
"customer": 15446,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": true,
"status": "paid",
"chase": false,
"next_chase_on": null,
"collection_mode": "auto",
"attempt_count": 1,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0017",
"date": 1416290402,
"due_date": null,
"payment_terms": "Auto-Charged",
"items": [
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 5,
"unit_cost": 45,
"amount": 225,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 225,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 228.85,
"balance": 228.85,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ/pdf",
"created_at": 1415229885
}
Invoiced\Invoice JSON: {
"id": 46226,
"customer": 15446,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": true,
"status": "paid",
"chase": false,
"next_chase_on": null,
"collection_mode": "auto",
"attempt_count": 1,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0017",
"date": 1416290402,
"due_date": null,
"payment_terms": "Auto-Charged",
"items": [
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 5,
"unit_cost": 45,
"amount": 225,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 225,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 228.85,
"balance": 228.85,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfDasdfGPBmyd6FwXZ/pdf",
"created_at": 1415229885
}
When an invoice is automatically collected we will perform the charge automatically. If a payment attempts fails then another attempt will be scheduled according to your retry settings. Or, you can trigger a charge attempt manually using this endpoint.
HTTP Request
POST /invoices/:id/pay
Delete an invoice
curl "https://api.invoiced.com/invoices/:id" \
-u {API_KEY}: \
-X DELETE
invoice.delete
<?php
$invoice->delete();
The above command returns
204 No Content
This endpoint deletes a specific invoice.
HTTP Request
DELETE /invoices/:id
List all invoices
curl "https://api.invoiced.com/invoices" \
-u {API_KEY}:
invoices, metadata = invoiced.Invoice.list(:per_page => 3)
<?php
list($invoices, $metadata) = $invoiced->Invoice->list(['per_page' => 3]);
The above command returns JSON structured like this:
[
{
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
},
{ ... },
{ ... }
]
[
#<Invoiced::Invoice:0x3fdbf95e4d08 id=46225> JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
},
#<Invoiced::Invoice:0x3fdbf95e4d09 id=15445> JSON: { ... },
#<Invoiced::Invoice:0x3fdbf95e4d10 id=15446> JSON: { ... }
]
[
Invoiced\Invoice JSON: {
"id": 46225,
"customer": 15444,
"name": null,
"currency": "usd",
"draft": false,
"sent": false,
"closed": false,
"paid": false,
"status": "not_sent",
"chase": false,
"next_chase_on": null,
"collection_mode": "manual",
"attempt_count": 0,
"next_payment_attempt": null,
"theme": null,
"subscription": null,
"number": "INV-0016",
"date": 1416290400,
"due_date": 1417500000,
"payment_terms": "NET 14",
"items": [
{
"id": 7,
"stored_item": null,
"plan": null,
"type": "product",
"name": "Copy Paper, Case",
"description": null,
"quantity": 1,
"unit_cost": 45,
"amount": 45,
"discounts": [],
"taxes": []
},
{
"id": 8,
"stored_item": null,
"plan": null,
"type": "service",
"name": "Delivery",
"description": "",
"quantity": 1,
"unit_cost": 10,
"amount": 10,
"discounts": [],
"taxes": []
}
],
"terms": null,
"notes": null,
"subtotal": 55,
"discounts": [],
"taxes": [
{
"id": 20554,
"amount": 3.85,
"rate": null
}
],
"total": 51.15,
"balance": 51.15,
"url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY",
"pdf_url": "https://dundermifflin.invoiced.com/invoices/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415229884
},
Invoiced\Invoice JSON: { ... },
Invoiced\Invoice JSON: { ... }
]
This endpoint retrieves all invoices.
HTTP Request
GET /invoices
Query Parameters
Parameter | Description |
---|---|
sort string | Column to sort by, i.e. name asc |
filter object | Filter object |
start_date timestamp | Restricts the results to invoices on or after the given timestamp |
end_date timestamp | Restricts the results to invoices on or before the given timestamp |
Transactions
Transactions can represent a charge
, payment
, refund
, or adjustment
.
We record charge
and refund
transactions for you that happen through Invoiced. The payment
transaction type is designated for recording offline payments like checks. Finally, an adjustment
transaction represents any additional credit or debits to a customer’s balance.
Most transactions will be associated with an invoice, however, not all. For example, if you wanted to credit your customer for $20 you would create an adjustment
transaction for -$20 using the customer ID only instead of the invoice ID.
We currently support the following payment methods on transactions:
credit_card
ach
bitcoin
paypal
wire_transfer
check
cash
other
Transaction Object
Attributes
{
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Invoiced\Transaction JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Parameter | Type | Description |
---|---|---|
id | integer | The transaction’s unique ID |
customer | integer | Associated Customer |
invoice | integer | Associated Invoice, if any |
theme | integer | Theme ID for rendering with custom themes |
date | timestamp | Transaction date |
type | string | Transaction type, charge , payment , refund , or adjustment |
method | string | Payment instrument used to facilitate transaction |
status | string | Transaction status, one of succeeded , pending , or failed |
gateway | string | Payment gateway that processed the transaction, if any |
gateway_id | string | Transaction ID from the payment gateway |
currency | string | 3-digit ISO 4217 currency code |
amount | number | Transaction amount |
fee | number | Processing fees |
notes | string | Internal notes |
sent | boolean | Indicates if the transaction receipt has been sent’ |
parent_transaction | integer | ID of the original transaction for refunds |
pdf_url | string | URL to download the invoice as a PDF |
created_at | timestamp | Timestamp when created |
Create a transaction
curl "https://api.invoiced.com/transaction" \
-u {API_KEY}: \
-d invoice=44648 \
-d method="check" \
-d gateway_id="1450" \
-d amount=800
invoiced.Transaction.create(
:invoice => 44648,
:method => "check",
:gateway_id => "1450",
:amount => 800
)
<?php
$invoiced->Transaction->create([
'invoice' => 44648,
'method' => "check",
'gateway_id' => "1450",
'amount' => 800
]);
The above command returns JSON structured like this:
{
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": "1450",
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=30939> JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Invoiced\Transaction JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Create a new transaction with this endpoint.
HTTP Request
POST /transactions
Attributes
Parameter | Type | Description |
---|---|---|
customer | integer | Customer ID, required if invoice ID is not supplied |
invoice | integer | Invoice ID, if any |
type | string | Transaction type, charge , payment , refund , or adjustment - required |
date | timestamp | Transaction date, defaults to current timestamp |
theme | integer | Theme ID for rendering with custom themes |
method | string | Payment instrument used to facilitate transaction, defaults to other |
status | string | Transaction status, one of succeeded , pending , or failed , defaults to succeeded |
gateway | string | Payment gateway that processed the transaction, if any |
gateway_id | string | Transaction ID from the payment gateway, or check # if method is check |
currency | string | 3-digit ISO 4217 currency code |
amount | number | Transaction amount |
fee | number | Processing fees |
notes | string | Internal notes |
Retrieve a transaction
curl "https://api.invoiced.com/transactions/:id" \
-u {API_KEY}:
transaction = invoiced.Transaction.retrieve("{TRANSACTION_ID}")
<?php
$transaction = $invoiced->Transaction->retrieve("{TRANSACTION_ID}");
The above command returns JSON structured like this:
{
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Invoiced\Transaction JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
This endpoint retrieves a specific transaction.
HTTP Request
GET /transactions/:id
Update a transaction
curl "https://api.invoiced.com/transactions/:id" \
-u {API_KEY}: \
-d notes="Check was received by Jan" \
-X PATCH
transaction.notes = "Check was received by Jan"
transaction.save
<?php
$transaction->notes = "Check was received by Jan";
$transaction->save();
The above command returns JSON structured like this:
{
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": "Check was received by Jan",
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": "Check was received by Jan",
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Invoiced\Transaction JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": "Check was received by Jan",
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
}
Use this endpoint to update a transaction.
HTTP Request
PATCH /transactions/:id
Request Parameters
Parameter | Type | Description |
---|---|---|
date | timestamp | Transaction date, defaults to current timestamp |
theme | integer | Theme ID for rendering with custom themes |
method | string | Payment instrument used to facilitate transaction, defaults to other |
status | string | Transaction status, one of succeeded , pending , or failed , defaults to succeeded |
gateway | string | Payment gateway that processed the transaction, if any |
gateway_id | string | Transaction ID from the payment gateway, or check # if method is check |
currency | string | 3-digit ISO 4217 currency code |
amount | number | Transaction amount |
fee | number | Processing fees |
notes | string | Internal notes |
Send a receipt
curl "https://api.invoiced.com/transactions/:id/emails" \
-u {API_KEY}: \
-X POST
emails = transaction.send
<?php
$emails = $transaction->send();
The above command returns JSON structured like this:
[
{
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "payment_receipt_email",
"subject": "Receipt for your recent payment to Dunder Mifflin, Inc.",
"message": "Dear Client, we have attached a receipt for your most recent payment. Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
{ ... },
{ ... }
]
[
#<Invoiced::Email:0x3fdbf95e4d08 id="f45382c6fbc44d44aa7f9a55eb2ce731"> JSON: {
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "payment_receipt_email",
"subject": "Receipt for your recent payment to Dunder Mifflin, Inc.",
"message": "Dear Client, we have attached a receipt for your most recent payment. Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
#<Invoiced::Email:0x3fdasdf95e09 id="a0s36fbc44d44aa7f9a55easdfi8ce731"> JSON: { ... },
#<Invoiced::Email:0x3fdbffge4d10 id="s90f2c6fbc44sdfj8aa7f9a55eb2ce731"> JSON: { ... }
]
[
Invoiced\Email JSON: {
"id": "f45382c6fbc44d44aa7f9a55eb2ce731",
"state": "sent",
"reject_reason": null,
"email": "client@example.com",
"template": "payment_receipt_email",
"subject": "Receipt for your recent payment to Dunder Mifflin, Inc.",
"message": "Dear Client, we have attached a receipt for your most recent payment. Thank you!",
"opens": 0,
"opens_detail": [],
"clicks": 0,
"clicks_detail": [],
"created_at": 1436890047
},
Invoiced\Email JSON: { ... },
Invoiced\Email JSON: { ... }
]
This endpoint sends a PDF receipt to the customer.
HTTP Request
POST /transactions/:id/emails
Request Parameters
Parameter | Type | Description |
---|---|---|
to | array | Optional array of recipients like:[{"name": "Client", "email": "client@example.com"}] |
bcc | string | Optional comma-separated list of email addresses to be blind carbon copied |
subject | string | Optional subject |
message | string | Optional message body, otherwise the Payment Receipt Email template is used |
Refund a transaction
curl "https://api.invoiced.com/transactions/:id/refunds" \
-u {API_KEY}: \
-X POST
transaction = transaction.refund(:amount => 400)
<?php
$refund = $transaction->refund(['amount' => 400]);
The above command returns JSON structured like this:
{
"id": 20952,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "refund",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 400,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": 20939,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/20939pdf",
"created_at": 1415228628
}
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20952> JSON: {
"id": 20952,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "refund",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 400,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": 20939,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/20939pdf",
"created_at": 1415228628
}
Invoiced\Transaction JSON: {
"id": 20952,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "refund",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 400,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": 20939,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/20939pdf",
"created_at": 1415228628
}
You can issue a refund for charge
and payment
transactions. When a refund is issued for a charge
transaction we will attempt to initiate the refund over the payment gateway it happened on.
Of course, when refunding payment
transactions you would have to return the money to your customer. This endpoint simply provides a means to track any refunds that you issue for offline payments.
Partial refunds are allowed, however, the total amount refunded cannot exceed the original transaction amount.
HTTP Request
POST /transactions/:id/refunds
Request Parameters
Parameter | Type | Description |
---|---|---|
amount | number | Amount to refund - required |
Delete a transaction
curl "https://api.invoiced.com/transactions/:id" \
-u {API_KEY}: \
-X DELETE
transaction.delete
<?php
$transaction->delete();
The above command returns
204 No Content
This endpoint deletes a specific transaction.
HTTP Request
DELETE /transactions/:id
List all transactions
curl "https://api.invoiced.com/transactions" \
-u {API_KEY}:
transactions, metadata = invoiced.Transaction.list(:per_page => 3)
<?php
list($transactions, $metadata) = $invoiced->Transaction->list(['per_page' => 3]);
The above command returns JSON structured like this:
[
{
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
},
{ ... },
{ ... }
]
[
#<Invoiced::Transaction:0x3fdbf95e4d08 id=20939> JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
},
#<Invoiced::Transaction:0x3fdbf95e4d09 id=20940> JSON: { ... },
#<Invoiced::Transaction:0x3fdbf95e4d10 id=20941> JSON: { ... }
]
[
Invoiced\Transaction JSON: {
"id": 20939,
"customer": 15460,
"invoice": 44648,
"theme": null,
"date": 1410843600,
"type": "payment",
"method": "check",
"status": "succeeded",
"gateway": null,
"gateway_id": null,
"currency": "usd",
"amount": 800,
"fee": 0,
"notes": null,
"sent": false,
"failure_reason": null,
"parent_transaction": null,
"pdf_url": "https://dundermifflin.invoiced.com/payments/IZmXbVOPyvfD3GPBmyd6FwXY/pdf",
"created_at": 1415228628
},
Invoiced\Transaction JSON: { ... },
Invoiced\Transaction JSON: { ... }
]
This endpoint retrieves all transactions.
HTTP Request
GET /transactions
Query Parameters
Parameter | Description |
---|---|
sort string | Column to sort by, i.e. name asc |
filter object | Filter object |