Search
Voog.com
Search
Voog.com

Orders

Summary of order endpoints

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.

List all available orders for the current site

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"
    }
  }
]

Parameters

  • per_page - orders per response (default: 50; maximum: 250).
  • page - requested page (default: 1).

Filter attributes

Read more about filters.

  • Object order attributes: id, uuid, code, billing_address_id, shipping_address_id, status, discount_code, discount_id, 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.
  • Object customer attributes: id, name, email, phone.

Request invoices download for selected orders

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.

Parameters

  • 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:
    • as a query parameter in the form of an array (e.g. ?target_ids[]=1&target_ids[]=2).
    • as a query parameter in the form of a comma-separated list (e.g. ?target_ids=1,2).
    • as a request body parameter (e.g. {"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.

Request shipping package labels download for selected orders

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.

Parameters

  • 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:
    • as a query parameter in the form of an array (e.g. ?target_ids[]=1&target_ids[]=2).
    • as a query parameter in the form of a comma-separated list (e.g. ?target_ids=1,2).
    • as a request body parameter (e.g. {"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 data for a single order

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"
  }
}

Update attributes of a single order

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"
  }
}

Parameters

  • 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 note
  • shipping_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.

Get order's shipping method

Get order's shipping method. Compared to Shipping methods API, this endpoint returns the shipping method even if it has been deleted.

GET /admin/api/ecommerce/v1/orders/:id/shipping_method

Example request:

GET http://helloworld.voog.com/admin/api/ecommerce/v1/orders/48/shipping_method

Read more and see the example response.

Orders bulk update

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"
          ]
        }
      }
    ]
  }
}

Parameters

  • 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.

Product
Create online store
Create web page
Create blog
Integrations
All Features
Pricing
Company
About Voog
Affiliate program
Blog
Support
Help Centre
Contact Support
Follow Us
Facebook
Twitter
Instagram
Cookie settings Privacy Policy Terms & Conditions