Discounts

Summary of discount endpoints

• POST /admin/api/ecommerce/v1/discounts — create a new discount for the current site.
• GET /admin/api/ecommerce/v1/discounts/ — retrieve all discounts.
• GET /admin/api/ecommerce/v1/discounts/:id — retrieve a single discount.
• PUT /admin/api/ecommerce/v1/discounts/:id — update attributes of a single discount.
• DELETE /admin/api/ecommerce/v1/discounts/:id — remove a discount.

All endpoints take the optional include query parameter to enhance the response object (e.g. include=discount_objects,orders). include accepts the following comma-separated values:

• discount_objects — includes associated objects, i.e. products or categories.
• orders — includes associated orders.

The discount object

Attributes

• amount — Discount amount, (0..100) for a percentage type discount, any non-negative real value for a fixed discount.
• applies_to — Discount applicability. Allowed values:
  • cart_and_shipping — Discount applies to the entire shopping cart and shipping.
  • cart — Discount applies to the entire shopping cart, except shipping.
  • categories — Discount applies to a list of categories specified in discount_objects.
  • products — Discount applies to a list of products specified in discount_objects.
  • shipping — Discount applies to shipping only.
• code — Discount redemption code.
• currency — Discount currency, optional. Defaults to store currency.
• description — Discount description, optional.
• discount_objects — If discount_type is products or categories, an array of objects containing the following keys:
  • target_id — Product or category ID to which the discount applies.
  • target_type — Allowed values are product or category.
• discount_type — (percentage | fixed) Discount type.
• name — Discount name, optional.
• redemption_limit — Redemption limit, optional. If not specified, the discount redemption count is not limited.
• status — (open | closed) Discount status. Closed discounts cannot be redeemed.
• valid_from — Discount start date, optional. If a start date is specified, discounts cannot be redeemed before this date.
• valid_to — Discount end date, optional. If an end date is specified, discounts cannot be redeemed after this date.

Read only attributes

• orders_count — Number of orders with the discount applied.
• redeemable — A boolean value indicating whether the discount is currently redeemable. The discount is redeemable if its status is open, the number of times it has been redeemed is less than the redemption limit (if specified), and the current date is between the start and end dates (if specified).

Create a new discount for the current site

POST /admin/api/ecommerce/v1/discounts

Attributes

See above for a detailed description of the request payload.

Example request

POST https://helloworld.voog.com/admin/api/ecommerce/v1/discounts

{
  "code": "XMAS",
  "amount": "25",
  "discount_type": "percentage",
  "applies_to": "products",
  "status": "open",
  "discount_objects": [
    {
      "target_id": 18,
      "target_type": "product"
    },
    {
      "target_id": 204,
      "target_type": "product"
    }
  ]
}

Example response

Status: 201 Created

{
  "code": "XMAS",
  "orders": [],
  "discount_objects": [
    {
      "id": 29,
      "target_name": "Barrel",
      "created_at": "2017-12-14T09:24:50.000Z",
      "updated_at": "2017-12-14T09:24:50.000Z",
      "target_type": "product",
      "target_id": 204
    },
    {
      "id": 28,
      "target_name": "Ion drive",
      "created_at": "2017-12-14T09:24:50.000Z",
      "updated_at": "2017-12-14T09:24:50.000Z",
      "target_type": "product",
      "target_id": 18,
    }
  ],
  "valid_to": null,
  "id": 14,
  "applies_to": "products",
  "redemption_count": 0,
  "currency": "EUR",
  "status": "open",
  "created_at": "2017-12-14T09:24:50.254Z",
  "valid_from": null,
  "amount": "25.0",
  "name": null,
  "discount_type": "percentage",
  "redemption_limit": null,
  "updated_at": "2017-12-14T09:24:50.254Z",
  "description": null,
  "redeemable": true,
  "orders_count": 0
}

Retrieve all discounts

GET /admin/api/ecommerce/v1/discounts/

Attributes

See above for a detailed description of the response payload.

Query string parameters

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

Filter attributes

Read more about filters.

• Object discount attributes: id, name, description, code, status, applies_to, discount_type, valid_from, valid_to, amount, currency, redemption_limit, redemption_count, created_at, updated_at.
• Object discount_object attributes: id, target_id, target_type, target_name, created_at, updated_at.
• Object 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.

Example request

GET http://helloworld.voog.com/admin/api/ecommerce/v1/discounts

Example response

Status: 200 OK

[
  {
    "id": 14,
    "name": "Lorem ipsum",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "code": "XMAS",
    "status": "open",
    "applies_to": "products",
    "discount_type": "percentage",
    "amount": "25.0",
    "currency": "EUR",
    "redemption_count": 2,
    "redemption_limit": 2,
    "valid_from": null,
    "valid_to": null,
    "created_at": "2017-12-14T09:24:50.000Z",
    "updated_at": "2017-12-14T09:24:50.000Z",
    "redeemable": false,
    "orders_count": 0
  },
  {
    "id": 13,
    "name": null,
    "description": null,
    "code": "MIDSUMMER",
    "status": "open",
    "applies_to": "products",
    "discount_type": "fixed",
    "amount": "33.0",
    "currency": "EUR",
    "redemption_count": 0,
    "redemption_limit": null,
    "valid_from": null,
    "valid_to": null,
    "created_at": "2017-12-14T09:23:18.000Z",
    "updated_at": "2017-12-14T09:23:18.000Z",
    "redeemable": true,
    "orders_count": 0
  }
]

Retrieve a single discount

GET /admin/api/ecommerce/v1/discount/:id

Example request

GET http://helloworld.voog.com/admin/api/ecommerce/v1/discounts/14

Example response

Status: 200 OK

{
  "id": 14,
  "name": "Lorem ipsum",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "code": "XMAS",
  "status": "open",
  "applies_to": "products",
  "discount_type": "percentage",
  "amount": "25.0",
  "currency": "EUR",
  "redemption_count": 0,
  "redemption_limit": null,
  "valid_from": null,
  "valid_to": null,
  "created_at": "2017-12-14T09:24:50.000Z",
  "updated_at": "2017-12-14T09:24:50.000Z",
  "redeemable": false,
  "orders_count": 1
}

Update attributes of a single discount

PUT /admin/api/ecommerce/v1/discounts/:id

Attributes

See above for a detailed description of the request payload.

If discount_objects is omitted, the list of associated products or categories is not modified.

This request updates the discount with provided attributes.

Example request

PUT http://helloworld.voog.com/admin/api/ecommerce/v1/discounts/14

{
  "code": "JANUARY",
  "amount": "35"
}

Example response

Status: 200 OK

{
  "id": 14,
  "code": "JANUARY",
  "name": null,
  "description": null,
  "currency": "EUR",
  "status": "open",
  "updated_at": "2017-12-14T09:57:57.000Z",
  "valid_to": null,
  "valid_from": null,
  "redemption_limit": null,
  "applies_to": "products",
  "discount_objects": [
    {
      "id": 29,
      "target_name": "Barrel",
      "created_at": "2017-12-14T09:24:50.000Z",
      "updated_at": "2017-12-14T09:24:50.000Z",
      "target_type": "product",
      "target_id": 204
    },
    {
      "id": 28,
      "target_name": "Ion drive",
      "created_at": "2017-12-14T09:24:50.000Z",
      "updated_at": "2017-12-14T09:24:50.000Z",
      "target_type": "product",
      "target_id": 18,
    }
  ],
  "orders": [],
  "amount": "35.0",
  "created_at": "2017-12-14T09:24:50.000Z",
  "discount_type": "percentage",
  "redemption_count": 0,
  "redeemable": true,
  "orders_count": 0,
}

Remove a discount

DELETE /admin/api/ecommerce/v1/discounts/:code

This request deletes the given discount.

Example request

DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/discounts/14

Example response

Status: 204 No Content