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.

The GET endpoints accept an optional include parameter that enhances the response, e.g. include=discount_objects,orders. Supported values are:

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

Create a new discount for the current site

POST /admin/api/ecommerce/v1/discounts

Example data:

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

Parameters

• code - Discount redemption code.
• name - Discount name, optional.
• description - Discount description, optional.
• currency - Discount currency, optional. Defaults to store currency.
• amount - Discount amount, (0..100) for a percentage type discount, any non-negative real value for a fixed discount.
• discount_type - ("percentage" | "fixed") Discount type.
• 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.
• redemption_limit - Redemption limit, optional. If not specified, the discount redemption count is not limited.
• applies_to - Discount applicability. Allowed values:
  • products - Discount applies to a list of products specified in discount_objects.
  • categories - Discount applies to a list of categories specified in discount_objects.
  • cart - Discount applies to the entire shopping cart, except shipping.
  • shipping - Discount applies to shipping only.
  • cart_and_shipping - Discount applies to the entire shopping cart and shipping.
• 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.

Retrieve all discounts

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

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

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.

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

Update attributes of a single discount

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

This request updates the discount with provided attributes.

Example request:

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

Example data:

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

Parameters

• code - Discount redemption code.
• name - Discount name, optional.
• description - Discount description, optional.
• currency - Discount currency, optional. Defaults to store currency.
• amount - Discount amount, (0..100] for a percentage type discount, any non-negative real value for a fixed discount.
• discount_type - ("percentage" | "fixed") Discount type.
• 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.
• redemption_limit - Redemption limit, optional. If not specified, the discount redemption count is not limited.
• applies_to - Discount applicability. Allowed values:
  • products - Discount applies to a list of products specified in discount_objects.
  • categories - Discount applies to a list of categories specified in discount_objects.
  • cart - Discount applies to the entire shopping cart, except shipping.
  • shipping - Discount applies to shipping only.
  • cart_and_shipping - Discount applies to the entire shopping cart and shipping.
• discount_objects - If discount_type is products, 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.

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

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