Invoices

Invoice object

Attributes

Attributes

id string Unique object's identifier.

customer string The ID of the customer who will be billed. In read resources this field is expandable, returns the customer object. expandable

number number A unique, identifying number that appears on invoice header sent to the customer of this invoice. It's automatically assigned.

document string The ID of the document type for this invoice. Learn more about document types.

test_mode boolean Has the value true if the object exists in production mode or the value false if the object exists in test mode.

date date Closing date of the invoice. Typically this is the date on which invoice is generated.

due_date date Due date of the invoice.

lines list The list of line items for this invoice.

payments list The list of transactions for this invoice.

amount decimal Taxable subtotal of this invoice.

exempt decimal Non taxable subtotal of this invoice.

tax decimal Tax amount of this invoice.

tax_percent decimal Tax rate for this invoice.

subtotal decimal Sum of amount and exempt of this invoice.

total decimal Sum of subtotal and taxes of this invoice.

discount decimal Discount amount applicable to subtotal of this invoice.

discount_scheme string Scheme of the discount, one of $ or %.

period_start date The time when the service period for the billing starts.

period_end date The time when the service period for the billing ends.

collection_method string Method to collect payments of this invoice, one of automatically, deferred or deferred_dues.

local_file url URL to local format when document type of this invoice belong to a tax agency.

note string A note for the customer of this invoice.

fiscal_settings object An object with key pairs for tax agency.

subscription string The id of subscription if this invoice was created by a subscription.

status string Status of this invoice, one of draft, finalized or paid. Learn more about invoice status.

metadata object An object with key pairs for store custom information about this invoice.

user string Email of the user that created this invoice.

created datetime Date and time of the creation of this invoice.

updated datetime Date and time of the last update of this invoice.

Invoice object

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_APxT9s7X12ilP9Zx9O",
    "name": "Acme Nation LLC",
    "address": "17st, National Sub",
    "state": "IL",
    "country": "US",
    "phone": null,
    "email": "[e-mail]",
    "website": "https://www.stark.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 10923,
  "test_mode": false,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 4.0,
      "discount": 10.0
      "discount_scheme": "%"
    },
    ...
  ],
  "collection_method": "deferred_dues",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 50.5,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    },
    ...
  ],
  "amount": 100.50,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 100.50,
  "discount": 10.0,
  "discount_scheme": "$",
  "total": 90.50,
  "period_start": null,
  "period_end": null,
  "local_file": null,
  "note": "Hint: Chargeable to 2020-07-12",
  "fiscal_settings": {},
  "status": "finalized",
  "metadata": {},
  "user": "[e-mail]",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}

Create an invoice

POST https://api.piriod.com/invoices/

This endpoint creates an invoice for a given customer with status draft. After create the invoice use finalize resource for finish invoice.

Request Body

Name	Type	Description
customer	string	The id of the customer of this invoice.
document	string	The id of the document type of this invoice.
date	string	Closing date of this invoice.
due_date	string	Due date of this invoice.
collection_method	string	Method to collect payments of this invoice.
lines	array	The list of line items for this invoice.

200 Invoice successfully created.

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_APxT9s7X12ilP9Zx9O",
    "name": "Acme Nation LLC",
    "address": "17st, National Sub",
    "state": "IL",
    "country": "US",
    "phone": null,
    "email": "[e-mail]",
    "website": "https://www.stark.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 0,
  "test_mode": false,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 10.00,
      "amount": 12.00,
      "discount": 10.00
      "discount_scheme": "$"
    }
  ],
  "collection_method": "deferred",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 110.00,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    }
  ],
  "amount": 110.00,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 110.00,
  "discount": 10.00,
  "discount_scheme": "$",
  "total": 100.00,
  "period_start": null,
  "period_end": null,
  "local_file": null,
  "note": "Hint: Chargeable to 2020-07-12",
  "fiscal_settings": {},
  "status": "draft",
  "metadata": {},
  "user": "[e-mail]",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}

Retrieve an invoice

GET https://api.piriod.com/invoices/{id}/

This endpoint retrieves an invoice.

Path Parameters

Name	Type	Description
id	string	The id of the invoice object.

200 Invoice successfully retrieved.

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_APxT9s7X12ilP9Zx9O",
    "name": "Acme Nation LLC",
    "address": "17st, National Sub",
    "state": "IL",
    "country": "US",
    "phone": null,
    "email": "[e-mail]",
    "website": "https://www.stark.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 10923,
  "test_mode": false,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 10.00,
      "amount": 12.00,
      "discount": 10.00
      "discount_scheme": "$"
    }
  ],
  "collection_method": "deferred",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 110.00,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    }
  ],
  "amount": 110.00,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 110.00,
  "discount": 10.00,
  "discount_scheme": "$",
  "total": 100.00,
  "period_start": null,
  "period_end": null,
  "local_file": null,
  "note": "Hint: Chargeable to 2020-07-12",
  "fiscal_settings": {},
  "status": "draft",
  "metadata": {},
  "user": "[e-mail]",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}

Update an invoice

PATCH https://api.piriod.com/invoices/{id}/

This endpoint updates an invoice. Only invoices with status draft are updated.

Path Parameters

Name	Type	Description
id	string	The id of the invoice object.

Request Body

Name	Type	Description
customer	string	The id of the customer of the invoice.
test_mode	boolean	true if the object exists in test mode, false instead.
note	string	A note for the customer of this invoice.
period_start	string	The date when the service period for the billing starts.
period_end	string	The date when the service period for the billing ends.

200 Invoice successfully updated.

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_XT9UAs7y18ilAW72lX",
    "name": "Simple People LLC",
    "address": "12A Marina Avenue",
    "state": "CA",
    "country": "US",
    "phone": null,
    "email": "[e-mail]",
    "website": "https://www.spinversions.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 0,
  "test_mode": true,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 10.00,
      "amount": 12.00,
      "discount": 10.00
      "discount_scheme": "$"
    }
  ],
  "collection_method": "deferred",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 110.00,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    }
  ],
  "amount": 110.00,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 110.00,
  "discount": 10.00,
  "discount_scheme": "$",
  "total": 100.00,
  "period_start": "2020-06-01",
  "period_end": "2020-06-31",
  "local_file": null,
  "note": "Chargeable to 2020-06-31",
  "fiscal_settings": {},
  "status": "draft",
  "metadata": {},
  "user": "[e-mail]",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}

Destroy an invoice

DELETE https://api.piriod.com/invoices/{id}/

Destroy an invoice object. Only invoices with status draft are updated.

Path Parameters

Name	Type	Description
id	string	The id of the invoice object.

204 Invoice successfully destroyed.

Finalize an invoice

GET https://api.piriod.com/invoices/{id}/finalize/

This endpoint finalize an invoice. When the invoice is finalized, it is validated with the tax agency, if the invoice document type has tax regulations, you will no longer be able to update your data. The status attribute of the invoice object will become to finalized. The local_file attribute of the invoice object will have a url to get the file that was sent to the tax agency, normally it is a file with an .xml extension.

Path Parameters

Name	Type	Description
id	string	The id of invoice object.

200 Invoice successfully finalized.

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_XT9UAs7y18ilAW72lX",
    "name": "Simple People LLC",
    "address": "12A Marina Avenue",
    "state": "CA",
    "country": "US",
    "phone": null,
    "email": "[e-mail]",
    "website": "https://www.spinversions.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 0,
  "test_mode": true,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 10.00,
      "amount": 12.00,
      "discount": 10.00
      "discount_scheme": "$"
    }
  ],
  "collection_method": "deferred",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 110.00,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    }
  ],
  "amount": 110.00,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 110.00,
  "discount": 10.00,
  "discount_scheme": "$",
  "total": 100.00,
  "period_start": "2020-06-01",
  "period_end": "2020-06-31",
  "local_file": null,
  "note": "Chargeable to 2020-06-31",
  "fiscal_settings": {},
  "status": "finalized",
  "metadata": {},
  "user": "[e-mail]",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}

Retrieve an invoice PDF

GET https://api.piriod.com/invoices/{id}/pdf/

This endpoint retrieves a PDF representation of the invoice. Returns a Blob encoded in Base64.

Path Parameters

Name	Type	Description
id	string	The id of invoice object.

200 Invoice PDF representation successfully retrieved.

{
    "file": "JVBERi0xLjcKJeLjz9MKNiAwIG9iago8PCAvVHlwZSAvUGFnZS..."
}