An Order represents a sale or transfer that must be previously delivered before it can be invoiced.
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
| id | string | Unique order ID | |
| currency | string | Currency code derived from customer (read-only). | |
| customer | object | Full Customer object in responses. In write requests, send customer ID | |
| document | object | Full Document object in responses. In write requests, send document ID. | |
| date | date (YYYY-MM-DD) | Order issue date. | |
| number | integer | null | Fiscal / document number (usually assigned on finalize) |
| status | string | One of draft, finalized, cancelled (read-only in API writes) | |
| biller_status | string | One of void, pending, succeeded, failed | |
| shipping_type | string | Shipping / transfer type code | |
| amount | number | Taxable subtotal (auto-calculated) | |
| exempt | number | Exempt subtotal (auto-calculated) | |
| tax | number | Total taxes (auto-calculated) | |
| tax_percent | number | Effective tax rate (auto-calculated) | |
| total | number | Order grand total (auto-calculated) | |
| note | string | null | Free text note |
| address | string | null | Optional shipping/reference address |
| state | string | null | State ID (state objects) |
| carrier_id | integer | null | Carrier identifier |
| carrier_name | string | null | Carrier name |
| licence_plate | string | null | Vehicle plate |
| imported | string | Indicates imported record (read-only) | |
| test_mode | boolean | false | Test mode flag |
| tax_settings | object | Country-specific fiscal settings | |
| tax_agency | object | Tax authority/biller payload/status metadata (read-only) | |
| local_file | string | null | File path/URL for locally stored fiscal file (read-only) |
| freight_modality | integer | null | Freight modality code (Brazil transport) |
| transporter_tax_id | string | null | Transporter tax ID |
| transporter_name | string | null | Transporter legal name |
| transporter_state_tax_id | string | null | Transporter state tax registration |
| transporter_address | string | null | Transporter address |
| transporter_city_name | string | null | Transporter city |
| transporter_state_code | string | null | Transporter state code (2 chars) |
| lines | array of objects | Order line items | |
| references | array of objects | Document references | |
| volumes | array of objects | Transport volumes | |
| created | datetime | now | Creation timestamp (read-only) |
| updated | datetime | now | Last update timestamp (read-only) |
Volumes
| Attribute | Type | Default | Description |
|---|---|---|---|
| quantity | integer | null | Number of packages/volumes |
| kind | string | null | Volume type / kind |
| net_weight | number | null | Net weight |
| gross_weight | number | null | Gross weight |
Tax settings
The following corresponds to the definition of the fields used to define tax aspects specific to the different electronic invoicing regulations of each country.
Brasil
| Attribute | Type | Default | Description |
|---|---|---|---|
| br_operation_nature | string | null | Legal description of the operation shown in NF-e (natureza da operação), e.g. import, transfer, demo shipment |
| br_operation_type | string | Direction of goods movement in NF-e (Incoming for entry, Outgoing for exit) | |
| br_destination | string | Destination scope of the operation (Internal, interstate, or international/external) | |
| br_city_code | string | IBGE city code of the NF-e issuance location | |
| br_series | integer | Fiscal series number used to group/sequence NF-e documents | |
| br_issue_datetime | datetime | Official NF-e issuance timestamp | |
| br_exit_datetime | datetime | null | Date-time when goods actually leave/enter (physical movement timestamp) |
| br_purpose_type | string | Fiscal purpose of issuance (normal, complementary, adjustment, return) | |
| br_final_consumer_indicator | string | Indicates whether the recipient is the final consumer | |
| br_presence_indicator | string | Indicates buyer presence/operation context (in-person, internet, tele-sales, etc.) | |
| br_intermediary_indicator | string | Indicates whether the sale/operation used an intermediary platform (marketplace/intermediary) | |
| br_print_type | string | DANFE print layout/mode to be used for the NF-e | |
| br_emission_type | string | string | Emission mode (normal or contingency mode) |
| br_process_issuer | string | string | Identifies the system/process that generated the NF-e |
| br_process_version | string | string | Version of the emitting process/system |
| br_additional_fiscal_information | string | string | Additional information for tax authority only (infAdFisco) |
| br_additional_information | string | string | Complementary information for recipient/DANFE (infCpl) |
| br_references | array | Referenced fiscal documents for this NF-e (each item points to another NF-e access key) | |
| br_payment_method | string | NF-e payment method code for the payment group (e.g. 90 = no payment at issuance) | |
| br_payment_amount | number | Amount informed in the payment detail group. If omitted, payload builder derives it from order totals/rules |
Object sample
{
"id": "ord_tnlUbv0YSTbzmsx7oH",
"customer": {
"id": "cus_APxT9s7X12ilP9Zx9O",
"name": "Acme Nation LLC",
"address": "17st, National Sub",
"state": "IL",
"country": "US",
"phone": null,
"email": "[email protected]",
"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"
}