Developers

Shopping carts

Summary of shopping cart endpoints

All endpoints take optional query parameters that enhance the response objects:

  • include — enhance the response objects (e.g. include=variants,translations). Supported values are:
    • items - includes cart item lines.
    • shipping_address - includes cart shipping_address block.
    • billing_address - includes cart billing_address block.
    • translations — includes translations for all translatable objects and keys.
  • language_code — display all top-level values in the given language context.

Create a new shopping cart for the current site

POST /admin/api/ecommerce/v1/carts

This endpoint also allows anonymous access.

Example data:

{
  "items": [
    {
      "id": 1,
      "quantity": 1
    }
  ],
  "shipping_method_id": 8,
  "shipping_method_option": "option 1",
  "customer": {
    "name": "John Doe",
    "email": "john@doe.com",
    "phone": "1234567"
  },
  "currency": "EUR"
}

Example response:

Status: 201 Created
{
  "uuid": "7d5fea69-d68f-4cad-8502-be32e580bd6c",
  "currency": "EUR",
  "items_subtotal_amount": "12.5",
  "items_tax_amount": "2.5",
  "shipping_subtotal_amount": "2.5",
  "shipping_tax_amount": "0.5",
  "shipping_total_amount": "3.0",
  "shipping_tax_rate": "20.0",
  "shipping_method_id": 8,
  "shipping_method_option": "option 1",
  "item_amounts": [
    {
      "subtotal_amount": "12.5",
      "tax_rate": "20.0",
      "tax_amount": "2.5",
      "total_amount": "15.0"
    }
  ],
  "tax_amounts": [
    {
      "subtotal_amount": "15.0",
      "tax_rate": "20.0",
      "tax_amount": "3.0"
    }
  ],
  "total_amount": "18.0",
  "gateway_code": null,
  "payment_method": null,
  "return_url": "http://helloworld.voog.com/products/product-1",
  "note": null,
  "created_at": "2017-04-17T11:51:39.581Z",
  "updated_at": "2017-04-17T11:51:39.581Z",
  "shipping_method": {
    "id": 2,
    "name": "Advanced shipping",
    "description": "Advanced shipping with multiple options",
    "amount": "2.5",
    "tax_rate": "20.0",
    "option": "option 1"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@doe.com",
    "phone": "1234567"
  },
  "items": [
    {
      "id": 1,
      "kind": "payment",
      "status": "paid",
      "product_id": 1,
      "note": null,
      "price": "12.5",
      "quantity": 1,
      "amount": "15.0",
      "subtotal_amount": "12.5",
      "tax_amount": "2.5",
      "tax_rate": "20.0",
      "created_at": "2017-03-24T08:46:22.000Z",
      "updated_at": "2017-03-24T08:46:22.000Z",
      "product": {
        "id": 1,
        "is_variant": true,
        "name": "Sample product",
        "variant_attributes_text": "Color: Red",
        "variant_attributes": [
          "variant_type": {
            "id": 1,
            "name": "Color"
          },
          "variant_value": {
            "id": 1,
            "name": "Red"
          }
        ]
      },
      "product_name": "Sample product"
    }
  ],
  "metainfo":{
    "checkout_allowed": true,
    "update_allowed": true
  },
  "urls": {
    "url": "http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c",
    "checkout_url": "http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c/checkout"
  },
  "payment_methods": [
    {
      "code": "swedbank",
      "gateway_code": "makecommerce"
    }, {
      "code": "offline",
      "gateway_code": "offline"
    }
  ]
}

Parameters

  • items — array of items (product_id, quantity, note) that are added to the cart.
  • gateway_code — name of the chosen gateway, e.g. paypal, makecommerce, offline.
  • payment_method — name of the chosen gateway's method, e.g. paypal-creditcard, swedbank, seb, offline.
  • return_url — URL where all checkouts are eventually redirected.
  • shipping_method_id — chosen shipping method ID.
  • shipping_method_option — chosen shipping method option, if necessary.
  • customer — customer details (email, name, phone, language).
  • billing_address — billing address (name, company_name, address1, address2, city, zip_code, state, country_code, phone, instructions).
  • shipping_address — shipping address (name, company_name, address1, address2, city, zip_code, state, country_code, phone, instructions).
  • note — optional message to the store admin.

Get data for a single shopping cart

This endpoint also allows anonymous access.

GET /admin/api/ecommerce/v1/carts/:uuid

Example request:

GET http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c

Example response:

Status: 200 OK
{
  "uuid": "7d5fea69-d68f-4cad-8502-be32e580bd6c",
  "currency": "EUR",
  "items_subtotal_amount": "12.5",
  "items_tax_amount": "2.5",
  "shipping_subtotal_amount": "2.5",
  "shipping_tax_amount": "0.5",
  "shipping_total_amount": "3.0",
  "shipping_tax_rate": "20.0",
  "shipping_method_id": 8,
  "shipping_method_option": "option 1",
  "item_amounts": [
    {
      "subtotal_amount": "12.5",
      "tax_rate": "20.0",
      "tax_amount": "2.5",
      "total_amount": "15.0"
    }
  ],
  "tax_amounts": [
    {
      "subtotal_amount": "15.0",
      "tax_rate": "20.0",
      "tax_amount": "3.0"
    }
  ],
  "total_amount": "18.0",
  "gateway_code": null,
  "payment_method": null,
  "return_url": "http://helloworld.voog.com/products/product-1",
  "note": null,
  "created_at": "2017-04-17T11:51:39.581Z",
  "updated_at": "2017-04-17T11:51:39.581Z",
  "shipping_method": {
    "id": 2,
    "name": "Advanced shipping",
    "description": "Advanced shipping with multiple options",
    "amount": "2.5",
    "tax_rate": "20.0",
    "option": "option 1"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@doe.com",
    "phone": "1234567"
  },
  "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": ""
  },
  "items": [
    {
      "id": 1,
      "kind": "payment",
      "status": "paid",
      "product_id": 1,
      "note": null,
      "price": "12.5",
      "quantity": 1,
      "amount": "15.0",
      "subtotal_amount": "12.5",
      "tax_amount": "2.5",
      "tax_rate": "20.0",
      "created_at": "2017-03-24T08:46:22.000Z",
      "updated_at": "2017-03-24T08:46:22.000Z",
      "product": {
        "id": 1,
        "is_variant": true,
        "name": "Sample product",
        "variant_attributes_text": "Color: Red",
        "variant_attributes": [
          "variant_type": {
            "id": 1,
            "name": "Color"
          },
          "variant_value": {
            "id": 1,
            "name": "Red"
          }
        ]
      },
      "product_name": "Sample product"
    }
  ],
  "metainfo":{
    "checkout_allowed": true,
    "update_allowed": true
  },
  "urls": {
    "url": "http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c",
    "checkout_url": "http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c/checkout"
  },
  "payment_methods": [
    {
      "code": "swedbank",
      "gateway_code": "makecommerce"
    }, {
      "code": "offline",
      "gateway_code": "offline"
    }
  ]
}

Update attributes of a single shopping cart

PUT /admin/api/ecommerce/v1/carts/:uuid

This request updates the shopping cart with provided attributes.

This endpoint also allows anonymous access.

Example request:

PUT http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c

Example data:

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

Example response:

Status: 200 OK
{
  "uuid": "7d5fea69-d68f-4cad-8502-be32e580bd6c",
  "currency": "EUR",
  "items_subtotal_amount": "12.5",
  "items_tax_amount": "2.5",
  "shipping_subtotal_amount": "2.5",
  "shipping_tax_amount": "0.5",
  "shipping_total_amount": "3.0",
  "shipping_tax_rate": "20.0",
  "shipping_method_id": 8,
  "shipping_method_option": "option 1",
  "item_amounts": [
    {
      "subtotal_amount": "12.5",
      "tax_rate": "20.0",
      "tax_amount": "2.5",
      "total_amount": "15.0"
    }
  ],
  "tax_amounts": [
    {
      "subtotal_amount": "15.0",
      "tax_rate": "20.0",
      "tax_amount": "3.0"
    }
  ],
  "total_amount": "18.0",
  "gateway_code": null,
  "payment_method": null,
  "return_url": "http://helloworld.voog.com/products/product-1",
  "note": null,
  "created_at": "2017-04-17T11:51:39.581Z",
  "updated_at": "2017-04-17T11:51:39.581Z",
  "shipping_method": {
    "id": 2,
    "name": "Advanced shipping",
    "description": "Advanced shipping with multiple options",
    "amount": "2.5",
    "tax_rate": "20.0",
    "option": "option 1"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@doe.com",
    "phone": "1234567"
  },
  "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": ""
  },
  "items": [
    {
      "id": 1,
      "kind": "payment",
      "status": "paid",
      "product_id": 1,
      "note": null,
      "price": "12.5",
      "quantity": 1,
      "amount": "15.0",
      "subtotal_amount": "12.5",
      "tax_amount": "2.5",
      "tax_rate": "20.0",
      "created_at": "2017-03-24T08:46:22.000Z",
      "updated_at": "2017-03-24T08:46:22.000Z",
      "product": {
        "id": 1,
        "is_variant": true,
        "name": "Sample product",
        "variant_attributes_text": "Color: Red",
        "variant_attributes": [
          "variant_type": {
            "id": 1,
            "name": "Color"
          },
          "variant_value": {
            "id": 1,
            "name": "Red"
          }
        ]
      },
      "product_name": "Sample product"
    }
  ],
  "metainfo":{
    "checkout_allowed": true,
    "update_allowed": true
  },
  "urls": {
    "url": "http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c",
    "checkout_url": "http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c/checkout"
  },
  "payment_methods": [
    {
      "code": "swedbank",
      "gateway_code": "makecommerce"
    }, {
      "code": "offline",
      "gateway_code": "offline"
    }
  ]
}

Parameters

  • items — array of items (product_id, quantity, note) that are added to the cart.
  • gateway_code — name of the chosen gateway, e.g. "paypal", "makecommerce".
  • payment_method — name of the chosen gateway's method, e.g. "swedbank", "seb", "offline".
  • return_url — URL where all checkouts are eventually redirected.
  • shipping_method_id — chosen shipping method ID.
  • shipping_method_option — chosen shipping method option, if necessary.
  • customer — customer details (email, name, phone, language).
  • billing_address — billing address (name, company_name, address1, address2, city, zip_code, state, country_code, phone, instructions).
  • shipping_address — shipping address (name, company_name, address1, address2, city, zip_code, state, country_code, phone, instructions).
  • note — optional message to the store admin.

Checkout shopping cart

POST /admin/api/ecommerce/v1/carts/:uuid/checkout

This request starts the checkout process for the given shopping cart and returns a new Order.

Example request:

POST http://helloworld.voog.com/admin/api/ecommerce/v1/carts/7d5fea69-d68f-4cad-8502-be32e580bd6c/checkout

Example data:

  {
    "gateway_code": "offline",
    "payment_method": "offline"
  }

Example response:

Status: 200 OK
{
  "id": 1,
  "uuid": "c1e30dd5-d99f-4699-bea3-bf5cde9128ef",
  "code": "#1",
  "status": "created",
  "payment_status": "paid",
  "shipping_status": "not_dispatched",
  "currency": "EUR",
  "shipping_method_id": 8,
  "shipping_method_option": "option 1",
  "gateway_code": "offline",
  "gateway_name": null,
  "payment_method": "offline",
  "items_subtotal_amount": "12.5",
  "items_tax_amount": "2.5",
  "shipping_subtotal_amount": "2.5",
  "shipping_tax_amount": "0.5",
  "shipping_total_amount": "3.0",
  "shipping_tax_rate": "20.0",
  "total_amount": "18.0",
  "item_amounts": [
    {
      "subtotal_amount": "12.5",
      "tax_rate": "20.0",
      "tax_amount": "2.5",
      "total_amount": "15.0"
    }
  ],
  "tax_amounts": [
    {
      "subtotal_amount": "15.0",
      "tax_rate": "20.0",
      "tax_amount": "3.0"
    }
  ],
  "return_url": "https://helloworld.voog.com/products/product-1",
  "note": null,
  "issued_date": "2017-04-11",
  "value_date": "2017-04-12",
  "completed_at": null,
  "created_at": "2017-04-11T07:52:44.000Z",
  "updated_at": "2017-04-11T07:55:17.000Z",
  "shipping_method": {
    "id": 2,
    "name": "Advanced shipping",
    "description": "Advanced shipping with multiple options",
    "amount": "2.5",
    "tax_rate": "20.0",
    "option": "option 1"
  },
  "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": ""
  },
  "customer": {
    "name": "John Doe",
    "email": "john@doe.com",
    "phone": "1234567"
  },
  "items": [
    {
      "id": 1,
      "kind": "payment",
      "status": "paid",
      "product_id": 1,
      "note": null,
      "price": "12.5",
      "quantity": 1,
      "amount": "15.0",
      "subtotal_amount": "12.5",
      "tax_amount": "2.5",
      "tax_rate": "20.0",
      "created_at": "2017-03-24T08:46:22.000Z",
      "updated_at": "2017-03-24T08:46:22.000Z",
      "product": {
        "id": 1,
        "is_variant": true,
        "name": "Sample product",
        "variant_attributes_text": "Color: Red",
        "variant_attributes": [
          "variant_type": {
            "id": 1,
            "name": "Color"
          },
          "variant_value": {
            "id": 1,
            "name": "Red"
          }
        ]
      },
      "product_name": "Sample product"
    }
  ],
  "urls": {
    "url": "https://helloworld.voog.com/admin/api/ecommerce/v1/orders/1",
    "invoice_url": "https://helloworld.voog.com/admin/api/ecommerce/v1/invoices/c1e30dd5-d99f-4699-bea3-bf5cde9128ef"
  }
}

Parameters

  • gateway_code — name of the chosen gateway, e.g. paypal, makecommerce, offline.
  • payment_method — name of the chosen gateway's method, e.g. paypal-creditcard, swedbank, seb, offline.
  • return_url - return url for returning from external payment gateway.