All endpoints take optional query parameters that enhance the response objects:
include — enhance the response objects (e.g. include=items). Supported values are:
items - includes order item lines.shipping_address - includes order's shipping_address.billing_address - includes order's billing_address.language_code — display all top-level values in the given language context.Get list of orders for current site.
GET /admin/api/ecommerce/v1/orders?include=items,billing_address,shipping_address
Example response:
Status: 200 OK
[
{
"id": 48,
"uuid": "3347c171-de7a-45b7-a53c-85543a3de6f9",
"code": "#000134",
"status": "created",
"payment_status": "paid",
"shipping_status": "not_dispatched",
"currency": "EUR",
"shipping_method_id": 1,
"shipping_method_option": "Tallinna Ülemiste keskuse pakiautomaat",
"shipment_id": 36722,
"external_shipment_attrs": {
"id": "16793270818881",
"tracking_code": "00264300487155481756",
"tracking_url": "https://www.omniva.ee/era/jalgimine?barcode=00264300487155481756"
},
"gateway_code": "makecommerce",
"gateway_name": "Maksekeskus",
"payment_method": "swedbank",
"items_subtotal_amount": "1658.42",
"items_original_amount": "2475.25",
"items_tax_amount": "16.58",
"shipping_subtotal_amount": "3.5",
"shipping_original_amount": "3.5",
"shipping_tax_amount": "0.7",
"shipping_total_amount": "4.2",
"shipping_tax_rate": "20.0",
"total_amount": "1679.2",
"item_amounts": [
{
"subtotal_amount": "1658.42",
"original_amount": "2475.25",
"tax_rate": "1.0",
"tax_amount": "16.58",
"total_amount": "1675.0"
}
],
"tax_amounts": [
{
"subtotal_amount": "1658.42",
"tax_rate": "1.0",
"tax_amount": "16.58"
},
{
"subtotal_amount": "3.5",
"tax_rate": "20.0",
"tax_amount": "0.7"
}
],
"discount_code": "XMAS",
"return_url": "http://helloworld.voog.com",
"note": null,
"issued_date": "2017-12-18",
"value_date": "2017-12-18",
"paid_at": "2017-12-18",
"completed_at": null,
"gateway_transaction_id": "10c595c2-62a0-4554-882a-eb353b0a03a1",
"cart_rules_applied": false,
"custom_field_values": {
"a-date": "2021-03-03",
"a-time": "05:40:00",
"a-checkbox": true
},
"custom_field_metadata": {
"a-date": {
"label": "Please enter a date",
"kind": "date"
},
"a-time": {
"label": "Please enter a time",
"kind": "time"
},
"a-checkbox": {
"label": "Subscribe to the newsletter",
"kind": "checkbox"
},
},
"created_at": "2017-12-18T14:00:26.000Z",
"updated_at": "2017-12-18T14:00:26.000Z",
"shipping_method": {
"id": 1,
"name": "Omniva",
"description": "",
"amount": "3.5",
"tax_rate": "20.0",
"delivery_method": {
"code": "omniva_pup",
"provider_code": "omniva",
"configuration": {
"country_code": "ee"
}
},
"option": "Tallinna Ülemiste keskuse pakiautomaat"
},
"discount": {
"code": "XMAS",
"applies_to": "products",
"discount_type": "percentage",
"amount": "33.0",
"currency": "EUR",
"discount_objects": [
{
"target_id": 18,
"target_type": "product"
},
{
"target_id": 206,
"target_type": "product"
}
],
"id": 3
},
"billing_address": {
"name": "John Doe",
"company_name": "",
"address1": "Main Street 1",
"address2": "",
"city": "Tallinn",
"zip_code": "11612",
"state": null,
"country_code": "ee",
"phone": "1234567",
"instructions": ""
},
"shipping_address": {
"name": "John Doe",
"company_name": "",
"address1": "Suur-Sõjamäe tn 4",
"address2": null,
"city": "Tallinn",
"zip_code": "96113",
"state": null,
"country_code": "ee",
"phone": "1234567",
"instructions": "",
"delivery_method_code": "omniva_pup",
"delivery_method_external_code": "96113",
"pod_name": "Tallinna Ülemiste keskuse pakiautomaat"
},
"customer": {
"name": "John Doe",
"email": "john@doe.com",
"phone": "1234567",
"language": "en"
},
"items": [
{
"id": 88,
"kind": "payment",
"status": "paid",
"product_id": 207,
"note": null,
"price": "1658.42",
"original_price": "2475.25",
"quantity": 1,
"amount": "1675.0",
"subtotal_amount": "1658.42",
"tax_amount": "16.58",
"tax_rate": "1.0",
"created_at": "2017-12-18T14:00:26.000Z",
"updated_at": "2017-12-18T14:00:26.000Z",
"has_item_discount": true,
"product": {
"id": 207,
"is_variant": true,
"sku": null,
"parent_id": 200,
"name": "Ion drive",
"image_id": 88,
"image": {
"content_type": "image/jpeg",
"width": 948,
"height": 506,
"url": "http://media.voog.com/0000/0000/0001/photos/img.jpg",
"thumbnail": {
"content_type": "image/jpeg",
"width": 150,
"height": 80,
"url": "http://media.voog.com/0000/0000/0001/photos/img_medium.jpg"
},
"sizes": [
{
"content_type": "image/jpeg",
"width": 600,
"height": 320,
"url": "http://media.voog.com/0000/0000/0001/photos/img_block.jpg"
},
{
"content_type": "image/jpeg",
"width": 948,
"height": 506,
"url": "http://media.voog.com/0000/0000/0001/photos/img.jpg"
}
]
},
"variant_attributes_text": "Thrust: 950kN",
"variant_attributes": [
{
"variant_type": {
"id": 11,
"name": "Thrust"
},
"variant_value": {
"id": 30,
"name": "950kN"
}
}
]
},
"product_name": "Ion drive"
}
],
"urls": {
"url": "http://helloworld.voog.com/admin/api/ecommerce/v1/orders/48",
"invoice_url": "http://helloworld.voog.com/admin/api/ecommerce/v1/invoices/3347c171-de7a-45b7-a53c-85543a3de6f9"
}
}
]
per_page - orders per response (default: 50; maximum: 250).page - requested page (default: 1).Read more about filters.
order attributes: id, uuid, code, billing_address_id, shipping_address_id, status, discount_code,
payment_status, shipping_status, shipping_method_id, shipping_method_option, payment_method,
gateway_name, gateway_code, currency, shipping_subtotal_amount, shipping_tax_rate, shipping_tax_amount, shipping_total_amount,
shipping_original_amount, items_subtotal_amount, items_tax_amount, total_amount, tax_rate, note,
issued_date, value_date, paid_at, completed_at, created_at, updated_at.customer attributes: id, name, email, phone.This endpoint allows you to request invoices for specific orders by providing their IDs in target_ids as a parameter.
The request will be processed asynchronously, and upon completion, the download link will be sent to the email address of the user who made the request. The downloaded file will be in the ZIP format.
Additionally, you can use the endpoint's filter parameters to narrow down the list of orders to be included in the invoice download.
target_ids – an array of order IDs to be included in the download or the string "all" to include all orders matching the filter parameters. This parameter is required. You can provide the target_ids parameter:
?target_ids[]=1&target_ids[]=2).?target_ids=1,2).{"target_ids": [1, 2]}).Example request:
POST http://helloworld.voog.com/admin/api/ecommerce/v1/orders/download_invoices
Content-Type: application/json
{
"target_ids": [1, 2, 3]
}
Example response:
{
"export_file_id": 1,
"status": "pending",
"export_kind": "order_invoices",
"notification_email": "hello@voog.com",
"public_url": "http://media.voog.com/0000/0000/0001/export_files/5e3d1c59-748e-414a-bf8f-00cec452a8a7/invoices-20230125-092607.zip"
}
Possible values for status:
pending – the export request has been created and is waiting to be processed.started – the export request is being processed.success – the export request has been processed successfully.failure – the export request has failed.This endpoint allows you to request shipping package labels for specific orders by providing their IDs in target_ids as a parameter. The request will be processed asynchronously, and upon completion, the download link will be sent to the email address of the user who made the request. The downloaded file will be in the ZIP format.
Labels are generated only for orders that have a shipping method that supports package labels and related shipping provider integration is enabled.
Additionally, you can use the endpoint's filter parameters to narrow down the list of orders to be included in the invoice download.
target_ids – an array of order IDs to be included in the download or the string "all" to include all orders matching the filter parameters. This parameter is required. You can provide the target_ids parameter:
?target_ids[]=1&target_ids[]=2).?target_ids=1,2).{"target_ids": [1, 2]}).generate_shipment – a boolean value indicating whether to create a shipment (and shipping label) for an order if it doesn't have one yet.
If true, the order will be consigned to the shipping provider if it has a shipping method with an active delivery provider integration.
If false (default), only package labels for orders with existing shipments will be included in the download.Example request:
POST http://helloworld.voog.com/admin/api/ecommerce/v1/orders/download_package_labels
Content-Type: application/json
{
"target_ids": [1, 2, 3]
}
Example response:
{
"export_file_id": 1,
"status": "pending",
"export_kind": "order_package_labels",
"notification_email": "hello@voog.com",
"public_url": "http://media.voog.com/0000/0000/0001/export_files/5e3d1c59-748e-414a-bf8f-00cec452a8a7/package-labels-20230201-092607.zip"
}
Possible values for status:
pending – the export request has been created and is waiting to be processed.started – the export request is being processed.success – the export request has been processed successfully.failure – the export request has failed.GET /admin/api/ecommerce/v1/orders/:id?include=items,shipping_address,billing_address
Example request:
GET http://helloworld.voog.com/admin/api/ecommerce/v1/orders/48
Example response:
Status: 200 OK
{
"id": 48,
"uuid": "3347c171-de7a-45b7-a53c-85543a3de6f9",
"code": "#000134",
"status": "created",
"payment_status": "paid",
"shipping_status": "not_dispatched",
"currency": "EUR",
"shipping_method_id": 5,
"shipping_method_option": null,
"shipment_id": null,
"gateway_code": "makecommerce",
"gateway_name": "Maksekeskus",
"payment_method": "swedbank",
"items_subtotal_amount": "1658.42",
"items_original_amount": "2475.25",
"items_tax_amount": "16.58",
"shipping_subtotal_amount": "3.5",
"shipping_original_amount": "3.5",
"shipping_tax_amount": "0.7",
"shipping_total_amount": "4.2",
"shipping_tax_rate": "20.0",
"total_amount": "1679.2",
"item_amounts": [
{
"subtotal_amount": "1658.42",
"original_amount": "2475.25",
"tax_rate": "1.0",
"tax_amount": "16.58",
"total_amount": "1675.0"
}
],
"tax_amounts": [
{
"subtotal_amount": "1658.42",
"tax_rate": "1.0",
"tax_amount": "16.58"
},
{
"subtotal_amount": "3.5",
"tax_rate": "20.0",
"tax_amount": "0.7"
}
],
"discount_code": "XMAS",
"return_url": "http://helloworld.voog.com",
"note": null,
"issued_date": "2017-12-18",
"value_date": "2017-12-18",
"paid_at": "2017-12-18",
"completed_at": null,
"gateway_transaction_id": "10c595c2-62a0-4554-882a-eb353b0a03a1",
"cart_rules_applied": false,
"custom_field_values": {
"a-date": "2021-03-03",
"a-time": "05:40:00",
"a-checkbox": true
},
"custom_field_metadata": {
"a-date": {
"label": "Please enter a date",
"kind": "date"
},
"a-time": {
"label": "Please enter a time",
"kind": "time"
},
"a-checkbox": {
"label": "Subscribe to the newsletter",
"kind": "checkbox"
},
},
"created_at": "2017-12-18T14:00:26.000Z",
"updated_at": "2017-12-18T14:00:26.000Z",
"shipping_method": {
"id": 5,
"name": "Postal Service",
"description": "Send via mail",
"amount": "3.5",
"tax_rate": "20.0",
"delivery_method": null,
"option": null
},
"discount": {
"code": "XMAS",
"applies_to": "products",
"discount_type": "percentage",
"amount": "33.0",
"currency": "EUR",
"discount_objects": [
{
"target_id": 18,
"target_type": "product"
},
{
"target_id": 206,
"target_type": "product"
}
],
"id": 3
},
"billing_address": {
"name": "John Doe",
"company_name": "",
"address1": "Main Street 1",
"address2": "",
"city": "Tallinn",
"zip_code": "11612",
"state": null,
"country_code": "ee",
"phone": "1234567",
"instructions": ""
},
"shipping_address": {
"name": "John Doe",
"company_name": "",
"address1": "Main Street 1",
"address2": "",
"city": "Tallinn",
"zip_code": "11612",
"state": null,
"country_code": "ee",
"phone": "1234567",
"instructions": "",
"delivery_method_code": null,
"delivery_method_external_code": null,
"pod_name": null
},
"customer": {
"name": "John Doe",
"email": "john@doe.com",
"phone": "1234567",
"language": "en"
},
"items": [
{
"id": 88,
"kind": "payment",
"status": "paid",
"product_id": 207,
"note": null,
"price": "1658.42",
"original_price": "2475.25",
"quantity": 1,
"amount": "1675.0",
"subtotal_amount": "1658.42",
"tax_amount": "16.58",
"tax_rate": "1.0",
"created_at": "2017-12-18T14:00:26.000Z",
"updated_at": "2017-12-18T14:00:26.000Z",
"has_item_discount": true,
"product": {
"id": 207,
"is_variant": true,
"sku": null,
"parent_id": 200,
"name": "Ion drive",
"image_id": null,
"variant_attributes_text": "Thrust: 950kN",
"variant_attributes": [
{
"variant_type": {
"id": 11,
"name": "Thrust"
},
"variant_value": {
"id": 30,
"name": "950kN"
}
}
]
},
"product_name": "Ion drive"
}
],
"urls": {
"url": "http://helloworld.voog.com/admin/api/ecommerce/v1/orders/48",
"invoice_url": "http://helloworld.voog.com/admin/api/ecommerce/v1/invoices/3347c171-de7a-45b7-a53c-85543a3de6f9"
}
}
PUT /admin/api/ecommerce/v1/orders/:id
This request updates the order with provided attributes.
Example request:
PUT http://helloworld.voog.co/admin/api/ecommerce/v1/orders/48
Example data:
{
"status": "archived",
"shipping_status": "dispatched",
"note": "Picked up by customer",
"custom_field_values": {
"a-checkbox": false
},
"customer": {
"name": "Jane Doe",
"email": "jane@doe.com"
},
"billing_address": {
"name": "Jane Doe",
"address1": "Main Street 2",
},
"shipping_address": {
"name": "Jane Doe",
"address1": "Main Street 2",
"instructions": "Leave at the door"
}
}
Example response:
Status: 200 OK
{
"id": 48,
"uuid": "3347c171-de7a-45b7-a53c-85543a3de6f9",
"code": "#000134",
"status": "archived",
"payment_status": "paid",
"shipping_status": "dispatched",
"currency": "EUR",
"shipping_method_id": 5,
"shipping_method_option": null,
"shipment_id": null,
"gateway_code": "makecommerce",
"gateway_name": "Maksekeskus",
"payment_method": "swedbank",
"items_subtotal_amount": "1658.42",
"items_original_amount": "2475.25",
"items_tax_amount": "16.58",
"shipping_subtotal_amount": "3.5",
"shipping_original_amount": "3.5",
"shipping_tax_amount": "0.7",
"shipping_total_amount": "4.2",
"shipping_tax_rate": "20.0",
"total_amount": "1679.2",
"item_amounts": [
{
"subtotal_amount": "1658.42",
"original_amount": "2475.25",
"tax_rate": "1.0",
"tax_amount": "16.58",
"total_amount": "1675.0"
}
],
"tax_amounts": [
{
"subtotal_amount": "1658.42",
"tax_rate": "1.0",
"tax_amount": "16.58"
},
{
"subtotal_amount": "3.5",
"tax_rate": "20.0",
"tax_amount": "0.7"
}
],
"discount_code": "XMAS",
"return_url": "http://helloworld.voog.com",
"note": "Picked up by customer",
"issued_date": "2017-12-18",
"value_date": "2017-12-18",
"paid_at": "2017-12-18",
"completed_at": null,
"gateway_transaction_id": "10c595c2-62a0-4554-882a-eb353b0a03a1",
"cart_rules_applied": false,
"custom_field_values": {
"a-date": "2021-03-03",
"a-time": "05:40:00",
"a-checkbox": false
},
"custom_field_metadata": {
"a-date": {
"label": "Please enter a date",
"kind": "date"
},
"a-time": {
"label": "Please enter a time",
"kind": "time"
},
"a-checkbox": {
"label": "Subscribe to the newsletter",
"kind": "checkbox"
},
},
"created_at": "2017-12-18T14:00:26.000Z",
"updated_at": "2017-12-18T14:00:26.000Z",
"shipping_method": {
"id": 5,
"name": "Postal Service",
"description": "Send via mail",
"amount": "3.5",
"tax_rate": "20.0",
"delivery_method": null,
"option": null
},
"discount": {
"code": "XMAS",
"applies_to": "products",
"discount_type": "percentage",
"amount": "33.0",
"currency": "EUR",
"discount_objects": [
{
"target_id": 18,
"target_type": "product"
},
{
"target_id": 206,
"target_type": "product"
}
],
"id": 3
},
"billing_address": {
"name": "Jane Doe",
"company_name": "",
"address1": "Main Street 2",
"address2": "",
"city": "Tallinn",
"zip_code": "11612",
"state": null,
"country_code": "ee",
"phone": "1234567",
"instructions": ""
},
"shipping_address": {
"name": "Jane Doe",
"company_name": "",
"address1": "Main Street 2",
"address2": "",
"city": "Tallinn",
"zip_code": "11612",
"state": null,
"country_code": "ee",
"phone": "1234567",
"instructions": "Leave at the door",
"delivery_method_code": null,
"delivery_method_external_code": null,
"pod_name": null
},
"customer": {
"name": "Jane Doe",
"email": "jane@doe.com",
"phone": "1234567",
"language": "en"
},
"items": [
{
"id": 88,
"kind": "payment",
"status": "paid",
"product_id": 207,
"note": null,
"price": "1658.42",
"original_price": "2475.25",
"quantity": 1,
"amount": "1675.0",
"subtotal_amount": "1658.42",
"tax_amount": "16.58",
"tax_rate": "1.0",
"created_at": "2017-12-18T14:00:26.000Z",
"updated_at": "2017-12-18T14:00:26.000Z",
"has_item_discount": true,
"product": {
"id": 207,
"is_variant": true,
"sku": null,
"parent_id": 200,
"name": "Ion drive",
"image_id": null,
"variant_attributes_text": "Thrust: 950kN",
"variant_attributes": [
{
"variant_type": {
"id": 11,
"name": "Thrust"
},
"variant_value": {
"id": 30,
"name": "950kN"
}
}
]
},
"product_name": "Ion drive"
}
],
"urls": {
"url": "http://helloworld.voog.com/admin/api/ecommerce/v1/orders/48",
"invoice_url": "http://helloworld.voog.com/admin/api/ecommerce/v1/invoices/3347c171-de7a-45b7-a53c-85543a3de6f9"
}
}
status — Order general status, one of (created, cancelled, archived).payment_status — Order payment status, one of (unpaid, paid, pending, cancelled).shipping_status — Order shipping status, one of (dispatched, not_dispatched).note — Order noteshipping_method_option — Shipping method option. The option included in the payload must match
one of current order's shipping method options.customer — Customer information. The following fields can be updated: email, name, phone,
language.billing_address — Billing address information. The following fields can be updated: name,
company_name, vat_code, address1, address2, city, zip_code, state, country_code,
phone.shipping_address — Shipping address information. The following fields can be updated: name,
company_name, vat_code, address1, address2, city, zip_code, state, country_code,
phone, instructions.custom_field_values — Custom cart field values that are filled out for the
order.Apply requested updates to all requested orders in query (target_ids).
This endpoint also supports filter parameters to narrow down the list of orders to be updated.
When update of some order fails then other orders are still updated and the response contains the error details.
Example request:
PUT /admin/api/ecommerce/v1/orders
{
"actions": [
{
"target_field": "payment_status",
"action": "set",
"value": "paid"
},
{
"target_field": "shipping_status",
"action": "set",
"value": "dispatched"
},
{
"target_field": "status",
"action": "set",
"value": "archived"
}
],
"target_ids": [1, 2, 3]
}
Example response:
Status: 200 OK
{
"counters": {
"processed": 3,
"failed": 0
},
"processed_ids": [
1, 2, 3
],
"failed_ids": []
}
Example payload error response:
Status: 400 Bad Request
{
"errors": {
"payload": {
"actions": [
{
"index": 0,
"errors": [
{
"target_field": "action_not_supported"
}
]
}
],
"target_ids": "empty"
}
}
}
Example items error response:
Status: 409 Conflict
{
"counters": {
"processed": 0,
"failed": 1
},
"processed_ids": [],
"failed_ids": [
999
],
"errors": {
"items": [
{
"id": 999,
"errors": {
"payment_status": [
"is not included in the list"
]
}
}
]
}
}
actions – array of actions to apply to orders (required);
target_field - field to update (required).source_field - optional field name to use as source for the action. If not specified, the field itself is used as source.action – the action to perform on the field (required), one of:set – set the field to the given value. source_field value is copied to target_field when value is not specified or is blank.value – the value to use by the action (required). It can be a number, string or array depending on the action.
In case of statuses, the value must be one of the allowed values for the field (see parameters).target_ids – array of product ids to apply the actions to or string all to apply to all products (required).Supported target_field and source_field are: status, payment_status, shipping_status.