Orders

An Order represents a sale or transfer that must be previously delivered before it can be invoiced.

Order object

Attributes

Attribute

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 order header sent to the customer of this order. It's automatically assigned.

document string The ID of the document type for this order. 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 order. Typically this is the date on which order is generated.

address string An address where this order should be delivered.

carrier_id string The identifier of the person who must deliver this order.

carrier_name string The name of the person who must deliver this order.

state string A state where this order should be delivered.

licence_plate string The license plate of the vehicle that must deliver this order

shipping_type string The delivery type ID of this order. Learn more about shipping types.

lines list The list of line items for this order.

amount decimal Taxable subtotal of this order.

exempt decimal Non taxable subtotal of this order.

tax decimal Tax amount of this order.

tax_percent decimal Tax rate for this order.

total decimal Total of this order.

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

tax_agency object An object with key pairs for tax agency.

status string Status of this order, one of draft, finalized or cancelled. Learn more about order status.

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

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

Order object

{
  "id": "ord_tnlUbv0YSTbzmsx7oH",
  "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",
    "aggregations": {
      "balance": 5756.00,
      "sales": 14324.36,
      "sales_current_period": 1873.00
    },
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "number": 1726,
  "document": {
    "id": "US2",
    "name": "Order",
    "country": "US",
    "currency": {
      "id": "USD",
      "available": true,
      "conversion": null,
      "country": "US",
      "default": true,
      "is_chargeable": true,
      "name": "Dólar Estadounidense",
      "name_en": "American Dollar",
      "rounded": false
    }
  },
  "test_mode": false,
  "date": "2020-10-21",
  "address": null,
  "carrier_id": null,
  "carrier_name": null,
  "state": null,
  "licence_plate": null,
  "shipping_type": "1",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "My physical product",
      "description": null,
      "quantity": 4.0,
      "amount": 500.00,
      "exempt": false,
      "tax": null,
      "tax_percent": 0,
      "total": 2000.00,
      "created": "2020-10-21T12:01:53.430966-04:00",
      "updated": "2020-10-21T12:01:53.430966-04:00"
    }
  ],
  "amount": 2000.00,
  "exempt": null,
  "tax": null,
  "tax_percent": 0,
  "total": 2000.00,
  "local_file": null,
  "tax_agency": {},
  "status": "finalized",
  "created": "2020-10-21T09:55:07.138915-04:00",
  "updated": "2020-10-21T12:01:53.430966-04:00"
}

Order line object

Attributes

Attributes

name string

Name of product or service of this order line.

description string Description of product or service of this order line.

amount decimal Taxable amount of this order line.

exempt boolean Indicates if this order line is tax-related.

quantity decimal Quantity for this order line.

tax decimal Extra tax amount for this order line.

tax_percent decimal Extra tax rate for this order line.

total decimal Total of this order line.

created datetime Date and time of the creation of this order line.

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

Create an order

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

This endpoint creates a draft order. To convert a draft order to a real order use Finalize an order API method.

Request Body

Name	Type	Description
customer	string	The ID of the customer of this order.
document	string	The ID of the document type of this order.
date	string	Closing date of this order.
shipping_type	string	The shipping type of this order.
lines	array	A list of order lines of this order.

200 Order successfully created.

{
  "id": "ord_tnlUbv0YSTbzmsx7oH",
  "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",
    "aggregations": {
      "balance": 5756.00,
      "sales": 14324.36,
      "sales_current_period": 1873.00
    },
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "number": 1726,
  "document": {
    "id": "US2",
    "name": "Order",
    "country": "US",
    "currency": {
      "id": "USD",
      "available": true,
      "conversion": null,
      "country": "US",
      "default": true,
      "is_chargeable": true,
      "name": "Dólar Estadounidense",
      "name_en": "American Dollar",
      "rounded": false
    }
  },
  "test_mode": false,
  "date": "2020-10-21",
  "address": null,
  "carrier_id": null,
  "carrier_name": null,
  "state": null,
  "licence_plate": null,
  "shipping_type": "1",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "My physical product",
      "description": null,
      "quantity": 4.0,
      "amount": 500.00,
      "exempt": false,
      "tax": null,
      "tax_percent": 0,
      "total": 2000.00,
      "created": "2020-10-21T12:01:53.430966-04:00",
      "updated": "2020-10-21T12:01:53.430966-04:00"
    }
  ],
  "amount": 2000.00,
  "exempt": null,
  "tax": null,
  "tax_percent": 0,
  "total": 2000.00,
  "local_file": null,
  "tax_agency": {},
  "status": "draft",
  "created": "2020-10-21T09:55:07.138915-04:00",
  "updated": "2020-10-21T12:01:53.430966-04:00"
}

Retrieve an order

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

This endpoint retrieves an order.

Path Parameters

Name	Type	Description
id	string	The id of order object.

200 Order successfully retrieved.

{
  "id": "ord_tnlUbv0YSTbzmsx7oH",
  "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",
    "aggregations": {
      "balance": 5756.00,
      "sales": 14324.36,
      "sales_current_period": 1873.00
    },
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "number": 1726,
  "document": {
    "id": "US2",
    "name": "Order",
    "country": "US",
    "currency": {
      "id": "USD",
      "available": true,
      "conversion": null,
      "country": "US",
      "default": true,
      "is_chargeable": true,
      "name": "Dólar Estadounidense",
      "name_en": "American Dollar",
      "rounded": false
    }
  },
  "test_mode": false,
  "date": "2020-10-21",
  "address": null,
  "carrier_id": null,
  "carrier_name": null,
  "state": null,
  "licence_plate": null,
  "shipping_type": "1",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "My physical product",
      "description": null,
      "quantity": 4.0,
      "amount": 500.00,
      "exempt": false,
      "tax": null,
      "tax_percent": 0,
      "total": 2000.00,
      "created": "2020-10-21T12:01:53.430966-04:00",
      "updated": "2020-10-21T12:01:53.430966-04:00"
    }
  ],
  "amount": 2000.00,
  "exempt": null,
  "tax": null,
  "tax_percent": 0,
  "total": 2000.00,
  "local_file": null,
  "tax_agency": {},
  "status": "draft",
  "created": "2020-10-21T09:55:07.138915-04:00",
  "updated": "2020-10-21T12:01:53.430966-04:00"
}

Update an order

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

This endpoint updates an order. Only orders with draft status can be updated.

Path Parameters

Name	Type	Description
id	string	The id of order object.

Request Body

Name	Type	Description
date	string	Closing date of this order.

200

{
  "id": "ord_tnlUbv0YSTbzmsx7oH",
  "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",
    "aggregations": {
      "balance": 5756.00,
      "sales": 14324.36,
      "sales_current_period": 1873.00
    },
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "number": 1726,
  "document": {
    "id": "US2",
    "name": "Order",
    "country": "US",
    "currency": {
      "id": "USD",
      "available": true,
      "conversion": null,
      "country": "US",
      "default": true,
      "is_chargeable": true,
      "name": "Dólar Estadounidense",
      "name_en": "American Dollar",
      "rounded": false
    }
  },
  "test_mode": false,
  "date": "2020-10-25",
  "address": null,
  "carrier_id": null,
  "carrier_name": null,
  "state": null,
  "licence_plate": null,
  "shipping_type": "1",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "My physical product",
      "description": null,
      "quantity": 4.0,
      "amount": 500.00,
      "exempt": false,
      "tax": null,
      "tax_percent": 0,
      "total": 2000.00,
      "created": "2020-10-21T12:01:53.430966-04:00",
      "updated": "2020-10-21T12:01:53.430966-04:00"
    }
  ],
  "amount": 2000.00,
  "exempt": null,
  "tax": null,
  "tax_percent": 0,
  "total": 2000.00,
  "local_file": null,
  "tax_agency": {},
  "status": "draft",
  "created": "2020-10-21T09:55:07.138915-04:00",
  "updated": "2020-10-21T12:01:53.430966-04:00"
}

Destroy an order

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

Destroy an order object. Only orders with draft status can be updated.

Path Parameters

Name	Type	Description
id	string	The id of order object.

204 Order successfully destroyed.

Finalize an order

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

This endpoint finalize an order. When the order is finalized, it is validated with the tax agency, if the order document type has tax regulations, you will no longer be able to update your data. The status attribute of the order object will become finalized. The local_file attribute of the order 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 order object.

200 Order successfully finalized.

{
  "id": "ord_tnlUbv0YSTbzmsx7oH",
  "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",
    "aggregations": {
      "balance": 5756.00,
      "sales": 14324.36,
      "sales_current_period": 1873.00
    },
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "number": 1726,
  "document": {
    "id": "US2",
    "name": "Order",
    "country": "US",
    "currency": {
      "id": "USD",
      "available": true,
      "conversion": null,
      "country": "US",
      "default": true,
      "is_chargeable": true,
      "name": "Dólar Estadounidense",
      "name_en": "American Dollar",
      "rounded": false
    }
  },
  "test_mode": false,
  "date": "2020-10-25",
  "address": null,
  "carrier_id": null,
  "carrier_name": null,
  "state": null,
  "licence_plate": null,
  "shipping_type": "1",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "My physical product",
      "description": null,
      "quantity": 4.0,
      "amount": 500.00,
      "exempt": false,
      "tax": null,
      "tax_percent": 0,
      "total": 2000.00,
      "created": "2020-10-21T12:01:53.430966-04:00",
      "updated": "2020-10-21T12:01:53.430966-04:00"
    }
  ],
  "amount": 2000.00,
  "exempt": null,
  "tax": null,
  "tax_percent": 0,
  "total": 2000.00,
  "local_file": null,
  "tax_agency": {},
  "status": "finalized",
  "created": "2020-10-21T09:55:07.138915-04:00",
  "updated": "2020-10-21T12:01:53.430966-04:00"
}

Retrieve an order PDF

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

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

Path Parameters

Name	Type	Description
id	string	The id of order object.

200 Order PDF representation successfully retrieved.

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